add docs and update pragmas

Author: arr00

contracts/interfaces/IERC1271.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 // OpenZeppelin Contracts (last updated v5.3.0) (interfaces/IERC1271.sol)
 
-pragma solidity >=0.6.9;
+pragma solidity >=0.5.0;
 
 /**
  * @dev Interface of the ERC-1271 standard signature validation method for
@@ -13,5 +13,5 @@ interface IERC1271 {
      * @param hash      Hash of the data to be signed
      * @param signature Signature byte array associated with `hash`
      */
-    function isValidSignature(bytes32 hash, bytes memory signature) external view returns (bytes4 magicValue);
+    function isValidSignature(bytes32 hash, bytes calldata signature) external view returns (bytes4 magicValue);
 }

contracts/interfaces/IERC3156.sol

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 // OpenZeppelin Contracts (last updated v5.0.0) (interfaces/IERC3156.sol)
 
-pragma solidity >=0.8.20;
+pragma solidity >=0.5.0;
 
 import {IERC3156FlashBorrower} from "./IERC3156FlashBorrower.sol";
 import {IERC3156FlashLender} from "./IERC3156FlashLender.sol";

scripts/minimize-pragma.js

@@ -2,6 +2,8 @@ const { exec } = require('child_process');
 const fs = require('fs');
 
 let solcVersionsMaxPatch = ['0.5.16', '0.6.12', '0.7.6', '0.8.29'];
+
+// Generate an array of all the solc versions.
 const allSolcVersions = solcVersionsMaxPatch.flatMap(minorVersion => {
   let patchVersions = [];
   const maxPatchVersion = parseInt(minorVersion.split('.')[2]);
@@ -12,25 +14,40 @@ const allSolcVersions = solcVersionsMaxPatch.flatMap(minorVersion => {
   return patchVersions;
 });
 
+// Files that have been finalized and should not be modified again.
 let finalizedFiles = [];
 
 minimizeAllInterfacePragmas();
 
-async function getApplicablePragmas(file) {
-  const pragmas = await Promise.all(allSolcVersions.map(version => compileWithVersion(file, version)));
-  return pragmas;
+/**
+ * Main entry point that minimizes the pragma for all interface files. Draft interfaces are ignored.
+ */
+async function minimizeAllInterfacePragmas() {
+  const dirPath = 'contracts/interfaces';
+  const files = fs.readdirSync(dirPath);
+  for (const file of files) {
+    if (!file.endsWith('.sol') || file.startsWith('draft')) {
+      continue;
+    }
+    await minimizePragma(`${dirPath}/${file}`);
+  }
 }
 
+/**
+ * Minimize the pragma for a give file and all its dependencies.
+ * @param {*} file Absolute path to the file to minimize.
+ */
 async function minimizePragma(file) {
   if (finalizedFiles.includes(file)) {
     return;
   }
 
+  console.log(`Minimizing pragma in ${file}`);
+
   await updatePragmaWithDependencies(file);
 
   const sources = getFileSources(file);
   for (const source of sources) {
-    console.log(source);
     await minimizePragma(source);
   }
 
@@ -56,6 +73,19 @@ async function minimizePragma(file) {
   finalizedFiles.push(file);
 }
 
+/**
+ * Get the applicable pragmas for a given file by compiling it with all solc versions.
+ */
+async function getApplicablePragmas(file) {
+  const pragmas = await Promise.all(allSolcVersions.map(version => compileWithVersion(file, version)));
+  return pragmas;
+}
+
+/**
+ * Get the applicable pragmas for all parents of a given file. Each parent's applicability is merged.
+ * @param {*} parents
+ * @returns An array of applicable pragmas for all parents.
+ */
 async function getParentApplicablePragmas(parents) {
   let pragmas;
   for (const parent of parents) {
@@ -68,9 +98,15 @@ async function getParentApplicablePragmas(parents) {
   return pragmas;
 }
 
+/**
+ * Compile the given file with the specified solidity version using forge.
+ * @param {*} file Absolute path to the file to compile.
+ * @param {*} solcVersion Solc version to use for compilation. (ex: 0.8.4)
+ * @returns {Promise<{solcVersion: string, success: boolean}>} Compilation result.
+ */
 async function compileWithVersion(file, solcVersion) {
   return new Promise(resolve => {
-    exec(`forge build ${file} --ast --use ${solcVersion} --out out/out-solc${solcVersion}`, error => {
+    exec(`forge build ${file} --use ${solcVersion} --out out/out-solc${solcVersion}`, error => {
       if (error !== null) {
         return resolve({ solcVersion, success: false });
       }
@@ -79,17 +115,11 @@ async function compileWithVersion(file, solcVersion) {
   });
 }
 
-async function minimizeAllInterfacePragmas() {
-  const dirPath = 'contracts/interfaces';
-  const files = fs.readdirSync(dirPath);
-  for (const file of files) {
-    if (!file.endsWith('.sol') || file.startsWith('draft')) {
-      continue;
-    }
-    await minimizePragma(`${dirPath}/${file}`);
-  }
-}
-
+/**
+ * Gets the sources of a given file from the AST output. Note, must already be compiled with AST.
+ * @param {*} file Absolute path to the file to get sources from.
+ * @returns An array of sources for the file excluding the file itself.
+ */
 function getFileSources(file) {
   const contractName = file.split('/').at(-1);
 
@@ -104,6 +134,11 @@ function getFileSources(file) {
   return sources.filter(source => source !== file);
 }
 
+/**
+ * Updates the pragma in the given file to the newPragma version.
+ * @param {*} file Absolute path to the file to update.
+ * @param {*} newPragma New pragma version to set. (ex: >=0.8.4)
+ */
 function updatePragma(file, newPragma) {
   if (finalizedFiles.includes(file)) return;
 
@@ -115,6 +150,12 @@ function updatePragma(file, newPragma) {
   console.log(`Updated pragma in ${file} to ${newPragma}`);
 }
 
+/**
+ * Updates the pragma in the given file and all its dependencies to the newPragma version.
+ * This is a recursive function that will update all dependencies of the file.
+ * @param {*} file Absolute path to the file to update.
+ * @param {*} newPragma New pragma version to set. (ex: >=0.8.4). Defaults to >=0.5.0.
+ */
 async function updatePragmaWithDependencies(file, newPragma = '>=0.5.0') {
   updatePragma(file, newPragma);
 
@@ -127,6 +168,9 @@ async function updatePragmaWithDependencies(file, newPragma = '>=0.5.0') {
   }
 }
 
+/**
+ * Merge two lists of pragma compatibility results.
+ */
 function mergePragmaLists(pragmaList1, pragmaList2) {
   if (pragmaList1 === undefined || pragmaList2 === undefined) return pragmaList1 ?? pragmaList2;