[Chore] - Match contract docs locally (#493)

* add docgen for solidity changes to husky * add solidity docs * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com> * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com> * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com> * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com> * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com> * Update .husky/pre-commit.js Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com> Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com> --------- Signed-off-by: The Dark Jester <thedarkjester@users.noreply.github.com> Co-authored-by: kyzooghost <73516204+kyzooghost@users.noreply.github.com>
2026-01-06 22:23:55 -05:00 · 2025-01-06 14:12:38 +00:00
parent a83412e247
commit 643110c696
8 changed files with 180 additions and 51 deletions
--- a/.husky/pre-commit.js
+++ b/.husky/pre-commit.js
@@ -43,12 +43,17 @@ const FILE_EXTENSION_FILTERS = {
    [FILE_EXTENSION.SOLIDITY]: "\.sol$",
 };

-// File extension => script in package.json to run
+// File extension => script in package.json to run for linting
 const FILE_EXTENSION_LINTING_COMMAND = {
    [FILE_EXTENSION.TYPESCRIPT]: "pnpm run lint:ts:fix",
    [FILE_EXTENSION.SOLIDITY]: "pnpm run lint:sol:fix",
 };

+// File extension => script in package.json to run for documentation generation
+const FILE_EXTENSION_DOCUMENTATION_UPDATING_COMMAND = {
+    [FILE_EXTENSION.SOLIDITY]: "pnpm run solidity:docgen",
+};
+
 // Project => Path in monorepo
 const FOLDER_PATH = {
    [FOLDER.BRIDGEUI]: "bridge-ui/",
@@ -95,7 +100,8 @@ function main() {
            process.exit(1);
        }
        const changedFileExtensions = getChangedFileExtensions(folder);
-        executeLinting(folder, changedFileExtensions);
+        executeCommand(folder, changedFileExtensions, FILE_EXTENSION_LINTING_COMMAND);
+        executeCommand(folder, changedFileExtensions, FILE_EXTENSION_DOCUMENTATION_UPDATING_COMMAND);
    }

    updateGitIndex();
@@ -180,14 +186,15 @@ function getChangedFileExtensions(_folder) {
 }

 /**
- * Execute linting command
- * @param {FOLDER, FILE_EXTENSION[]}
+ * Execute command based on file extension
+ * @param {FOLDER, FILE_EXTENSION[], FILE_EXTENSION_LINTING_COMMAND | FILE_EXTENSION_DOCUMENTATION_UPDATING_COMMAND}
 */
-function executeLinting(_folder, _changedFileExtensions) {
+function executeCommand(_folder, _changedFileExtensions, _command) {
    for (const fileExtension of _changedFileExtensions) {
        const path = FOLDER_PATH[_folder];
-        const cmd = FILE_EXTENSION_LINTING_COMMAND[fileExtension];
-        console.log(`${fileExtension} change found in ${path}, linting...`);
+        const cmd = _command[fileExtension];
+        if (!cmd) return;
+        console.log(`${fileExtension} change found in ${path}, executing command ${cmd}`);
        try {
            // Execute command synchronously and stream output directly to the current stdout
            execSync(`
--- a/contracts/docs/api/LineaRollup.mdx
+++ b/contracts/docs/api/LineaRollup.mdx
@@ -24,14 +24,6 @@ bytes32 VERIFIER_UNSETTER_ROLE

 The role required to set/remove  proof verifiers by type.

-### GENESIS_SHNARF
-
-```solidity
-bytes32 GENESIS_SHNARF
-```
-
-The default genesis shnarf using empty/default hashes and a default state.
-
 ### SHNARF_EXISTS_DEFAULT_VALUE

 ```solidity
--- a/contracts/docs/api/interfaces/IPauseManager.mdx
+++ b/contracts/docs/api/interfaces/IPauseManager.mdx
@@ -70,6 +70,22 @@ Emitted when a pause type and its associated role are set in the `_pauseTypeRole
 | pauseType | enum IPauseManager.PauseType | The indexed type of pause. |
 | role | bytes32 | The indexed role associated with the pause type. |

+### PauseTypeRoleUpdated
+
+```solidity
+event PauseTypeRoleUpdated(enum IPauseManager.PauseType pauseType, bytes32 role, bytes32 previousRole)
+```
+
+Emitted when a pause type and its associated role are updated in the `_PauseTypeRoles` mapping.
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| pauseType | enum IPauseManager.PauseType | The indexed type of pause. |
+| role | bytes32 | The indexed role associated with the pause type. |
+| previousRole | bytes32 | The indexed previously found role associated with the pause type. |
+
 ### UnPauseTypeRoleSet

 ```solidity
@@ -85,6 +101,22 @@ Emitted when an unpause type and its associated role are set in the `_unPauseTyp
 | unPauseType | enum IPauseManager.PauseType | The indexed type of unpause. |
 | role | bytes32 | The indexed role associated with the unpause type. |

+### UnPauseTypeRoleUpdated
+
+```solidity
+event UnPauseTypeRoleUpdated(enum IPauseManager.PauseType unPauseType, bytes32 role, bytes32 previousRole)
+```
+
+Emitted when an unpause type and its associated role are updated in the `_unPauseTypeRoles` mapping.
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| unPauseType | enum IPauseManager.PauseType | The indexed type of unpause. |
+| role | bytes32 | The indexed role associated with the unpause type. |
+| previousRole | bytes32 | The indexed previously found role associated with the unpause type. |
+
 ### IsPaused

 ```solidity
@@ -101,6 +133,22 @@ error IsNotPaused(enum IPauseManager.PauseType pauseType)

 _Thrown when a specific pause type is not paused and expected to be._

+### PauseTypeNotUsed
+
+```solidity
+error PauseTypeNotUsed()
+```
+
+_Thrown when the unused paused type is used._
+
+### RolesNotDifferent
+
+```solidity
+error RolesNotDifferent()
+```
+
+_Thrown when trying to update a pause/unpause type role mapping to the existing role._
+
 ### pauseByType

 ```solidity
@@ -109,7 +157,8 @@ function pauseByType(enum IPauseManager.PauseType _pauseType) external

 Pauses functionality by specific type.

-_Requires the role mapped in pauseTypeRoles for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in pauseTypeRoles for the pauseType._

 #### Parameters

@@ -125,7 +174,8 @@ function unPauseByType(enum IPauseManager.PauseType _pauseType) external

 Unpauses functionality by specific type.

-_Requires the role mapped in unPauseTypeRoles for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in unPauseTypeRoles for the pauseType._

 #### Parameters

@@ -153,3 +203,41 @@ Check if a pause type is enabled.
 | ---- | ---- | ----------- |
 | pauseTypeIsPaused | bool | Returns true if the pause type if paused, false otherwise. |

+### updatePauseTypeRole
+
+```solidity
+function updatePauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the pause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+PAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+
+### updateUnpauseTypeRole
+
+```solidity
+function updateUnpauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the unpause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+UNPAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+
--- a/contracts/docs/api/interfaces/l1/ILineaRollup.mdx
+++ b/contracts/docs/api/interfaces/l1/ILineaRollup.mdx
@@ -308,14 +308,6 @@ error FinalizationStateIncorrect(bytes32 expected, bytes32 value)

 _Thrown when finalization state does not match._

-### FinalBlockNumberLessThanOrEqualToLastFinalizedBlock
-
-```solidity
-error FinalBlockNumberLessThanOrEqualToLastFinalizedBlock(uint256 finalBlockNumber, uint256 lastFinalizedBlock)
-```
-
-_Thrown when the final block number in finalization data is less than or equal to the last finalized block during finalization._
-
 ### FinalBlockStateEqualsZeroHash

 ```solidity
--- a/contracts/docs/api/lib/CallForwardingProxy.mdx
+++ b/contracts/docs/api/lib/CallForwardingProxy.mdx
@@ -1,9 +1,9 @@
 # `CallForwardingProxy`

-### target
+### TARGET

 ```solidity
-address target
+address TARGET
 ```

 The underlying target address that is called.
@@ -22,3 +22,9 @@ fallback() external payable

 Defaults to, and forwards all calls to the target address.

+### receive
+
+```solidity
+receive() external payable
+```
+
--- a/contracts/docs/api/lib/PauseManager.mdx
+++ b/contracts/docs/api/lib/PauseManager.mdx
@@ -22,6 +22,20 @@ This is used to unpause all unpausable functions.
 mapping(bytes32 => bool) pauseTypeStatuses
 ```

+### onlyUsedPausedTypes
+
+```solidity
+modifier onlyUsedPausedTypes(enum IPauseManager.PauseType _pauseType)
+```
+
+_Modifier to prevent usage of unused PauseType._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The PauseType value being checked. Requirements: - The type must not be UNUSED. |
+
 ### whenTypeAndGeneralNotPaused

 ```solidity
@@ -105,7 +119,8 @@ function pauseByType(enum IPauseManager.PauseType _pauseType) external

 Pauses functionality by specific type.

-_Requires the role mapped in `_pauseTypeRoles` for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in `_pauseTypeRoles` for the pauseType._

 #### Parameters

@@ -121,7 +136,8 @@ function unPauseByType(enum IPauseManager.PauseType _pauseType) external

 Unpauses functionality by specific type.

-_Requires the role mapped in `_unPauseTypeRoles` for the pauseType._
+_Throws if UNUSED pause type is used.
+Requires the role mapped in `_unPauseTypeRoles` for the pauseType._

 #### Parameters

@@ -149,3 +165,41 @@ Check if a pause type is enabled.
 | ---- | ---- | ----------- |
 | pauseTypeIsPaused | bool | Returns true if the pause type if paused, false otherwise. |

+### updatePauseTypeRole
+
+```solidity
+function updatePauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the pause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+PAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+
+### updateUnpauseTypeRole
+
+```solidity
+function updateUnpauseTypeRole(enum IPauseManager.PauseType _pauseType, bytes32 _newRole) external
+```
+
+Update the unpause type role mapping.
+
+_Throws if UNUSED pause type is used.
+Throws if role not different.
+UNPAUSE_ALL_ROLE role is required to execute this function._
+
+#### Parameters
+
+| Name | Type | Description |
+| ---- | ---- | ----------- |
+| _pauseType | enum IPauseManager.PauseType | The pause type value to update. |
+| _newRole | bytes32 | The role to update to. |
+
--- a/contracts/docs/scripts/updateSidebar.js
+++ b/contracts/docs/scripts/updateSidebar.js
@@ -1,10 +1,10 @@
 /* eslint-disable */
 // This script is meant to be executed in the root directory of https://github.com/Consensys/doc.linea, which has different linting rules
-// The purpose of this script is to modify the sidebars.js file to correctly include the autogenerated smart contract documentation 
+// The purpose of this script is to modify the sidebars.js file to correctly include the autogenerated smart contract documentation

 /**
 * PURPOSE
- * 
+ *
 * Modifies sidebars.js in the root directory of https://github.com/Consensys/doc.linea to correctly include smart contract documentation pages.
 * The sidebars.js file configures the sidebar for the documentation website @ https://docs.linea.build/
 */
@@ -70,7 +70,9 @@ function main() {
 */
 function removeExistingSmartContractSidebar(sidebarObject) {
  if (sidebarObject?.apiSidebar) {
-    sidebarObject.apiSidebar = sidebarObject?.apiSidebar.filter(sidebarSection => sidebarSection?.label !== SMART_CONTRACT_SIDEBAR_LABEL);
+    sidebarObject.apiSidebar = sidebarObject?.apiSidebar.filter(
+      (sidebarSection) => sidebarSection?.label !== SMART_CONTRACT_SIDEBAR_LABEL,
+    );
  }
 }

@@ -80,12 +82,7 @@ function removeExistingSmartContractSidebar(sidebarObject) {
 */
 function getSmartContractSidebar() {
  // Create and populate smart contract sidebar
-  const smartContractsPath = path.join(
-    __dirname,
-    "docs",
-    "api",
-    "linea-smart-contracts",
-  );
+  const smartContractsPath = path.join(__dirname, "docs", "api", "linea-smart-contracts");

  let smartContractSidebar = new FolderSidebar(
    SMART_CONTRACT_SIDEBAR_LABEL,
@@ -93,11 +90,7 @@ function getSmartContractSidebar() {
    false,
  );

-  populateFolderSidebar(
-    smartContractSidebar,
-    smartContractsPath,
-    ".mdx",
-  );
+  populateFolderSidebar(smartContractSidebar, smartContractsPath, ".mdx");

  return smartContractSidebar;
 }
@@ -120,10 +113,7 @@ function populateFolderSidebar(folderSidebar, subdirectoryPath, fileExtension) {

    // Base case => *.mdx file => Add relative path to sidebar
    if (fileMetadata.isFile() && fileNode.endsWith(fileExtension)) {
-      const relativePath = path.relative(
-        path.join(__dirname, "docs"),
-        filePath.split(fileExtension)[0],
-      );
+      const relativePath = path.relative(path.join(__dirname, "docs"), filePath.split(fileExtension)[0]);
      folderSidebar?.items.push(relativePath);
    }
  }
@@ -137,7 +127,7 @@ function populateFolderSidebar(folderSidebar, subdirectoryPath, fileExtension) {
    if (fileMetadata.isDirectory()) {
      let newFolderNode = new FolderSidebar(fileNode);
      populateFolderSidebar(newFolderNode, filePath, fileExtension);
-      // Add populated child FolderSidebar to current sidebar section 
+      // Add populated child FolderSidebar to current sidebar section
      folderSidebar?.items.push(newFolderNode);
    }
  }
@@ -153,8 +143,7 @@ function populateFolderSidebar(folderSidebar, subdirectoryPath, fileExtension) {
 */
 function createNewSidebarFile(sidebarObject) {
  // Create new sidebars.js file content
-  const sidebarFileLine1 =
-    "/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */";
+  const sidebarFileLine1 = "/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */";
  const sidebarFileLine2 = "const sidebars =";
  const sidebarFileLineFinal = "module.exports = sidebars;";
  const newSidebarFileContent = `${sidebarFileLine1}\n${sidebarFileLine2}\n${JSON.stringify(sidebarObject, null, 2)}\n\n${sidebarFileLineFinal}`;
--- a/contracts/package.json
+++ b/contracts/package.json
@@ -19,7 +19,8 @@
    "lint:ts:fix": "npx eslint --fix '**/*.{js,ts}'",
    "lint": "pnpm run lint:sol && npm run lint:ts && npm run prettier",
    "lint:fix": "pnpm run lint:sol:fix && npm run lint:ts:fix && npm run prettier:fix",
-    "clean": "rimraf .openzeppelin build cache node_modules typechain-types coverage coverage.json"
+    "clean": "rimraf .openzeppelin build cache node_modules typechain-types coverage coverage.json",
+    "solidity:docgen": "npx hardhat docgen"
  },
  "devDependencies": {
    "@ethereumjs/util": "9.0.3",