feat(docs): autocommit changes to solidity docs and omit private stat…

…e vars and functions (#490)
taikoxyz · Jan 4, 2023 · dbf8db9 · dbf8db9
1 parent b6345e2
commit dbf8db9
Show file tree

Hide file tree

Showing 14 changed files with 121 additions and 78 deletions.
diff --git a/.github/workflows/solidity.yml b/.github/workflows/solidity.yml
@@ -68,6 +68,12 @@ jobs:
         working-directory: ./packages/protocol
         run: pnpm export:docs
 
+      - uses: stefanzweifel/git-auto-commit-action@v4
+        name: protocol - Auto Commit Solidity Docs
+        if: github.ref != 'refs/heads/main'
+        with:
+          commit_message: "chore(docs): auto commit solidity docs"
+
       - name: protocol - Deploy L1 Contracts
         working-directory: ./packages/protocol
         run: pnpm deploy:hardhat

diff --git a/packages/protocol/hardhat.config.ts b/packages/protocol/hardhat.config.ts
@@ -22,6 +22,7 @@ const config: HardhatUserConfig = {
             "thirdparty/",
             "common/EssentialContract.sol",
         ],
+        outputDir: "../website/docs/smart-contracts/",
         pages: "files",
         templates: "./solidity-docgen/templates",
     },

diff --git a/packages/protocol/package.json b/packages/protocol/package.json
@@ -5,7 +5,7 @@
   "scripts": {
     "compile": "pnpm hardhat preprocess && pnpm hardhat compile",
     "export:abi": "pnpm hardhat clear-abi && pnpm hardhat export-abi",
-    "export:docs": "pnpm hardhat docgen && pnpm prettier --write ./docs/**/*.md",
+    "export:docs": "pnpm hardhat docgen && pnpm prettier --write ../website/docs/smart-contracts/**/*.md",
     "clean": "rm -rf abis cache && pnpm hardhat clean",
     "lint:sol": "pnpm prettier '**/*.sol' --write && pnpm solhint 'contracts/**/*.sol' --fix",
     "eslint": "pnpm exec eslint --ignore-path .eslintignore --ext .js,.ts .",
@@ -71,7 +71,7 @@
     "rlp": "^3.0.0",
     "solhint": "^3.3.7",
     "solidity-coverage": "^0.8.2",
-    "solidity-docgen": "^0.6.0-beta.29",
+    "solidity-docgen": "^0.6.0-beta.34",
     "ts-node": "^10.5.0",
     "typechain": "^5.2.0",
     "typescript": "^4.5.5"

diff --git a/packages/protocol/solidity-docgen/templates/common.hbs b/packages/protocol/solidity-docgen/templates/common.hbs
@@ -9,7 +9,9 @@
 {{{natspec.notice}}}
 
 {{#if natspec.dev}}
+{{#unless (eq visibility "internal")}}
 _{{{natspec.dev}}}_
+{{/unless}}
 {{/if}}
 
 {{#if natspec.params}}
@@ -30,5 +32,4 @@ _{{{natspec.dev}}}_
 {{#each returns}}
 | {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} |
 {{/each}}
-{{/if}}
-
+{{/if}}
diff --git a/packages/website/docs/smart-contracts/L1/LibData.md b/packages/website/docs/smart-contracts/L1/LibData.md
@@ -0,0 +1,105 @@
+## LibData
+
+### BlockMetadata
+
+```solidity
+struct BlockMetadata {
+  uint256 id;
+  uint256 l1Height;
+  bytes32 l1Hash;
+  address beneficiary;
+  bytes32 txListHash;
+  bytes32 mixHash;
+  bytes extraData;
+  uint64 gasLimit;
+  uint64 timestamp;
+  uint64 commitHeight;
+  uint64 commitSlot;
+}
+```
+
+### ProposedBlock
+
+```solidity
+struct ProposedBlock {
+  bytes32 metaHash;
+  address proposer;
+  uint64 proposedAt;
+}
+```
+
+### ForkChoice
+
+```solidity
+struct ForkChoice {
+  bytes32 blockHash;
+  uint64 provenAt;
+  address[] provers;
+}
+```
+
+### State
+
+```solidity
+struct State {
+  mapping(uint256 => bytes32) l2Hashes;
+  mapping(uint256 => struct LibData.ProposedBlock) proposedBlocks;
+  mapping(uint256 => mapping(bytes32 => struct LibData.ForkChoice)) forkChoices;
+  mapping(address => mapping(uint256 => bytes32)) commits;
+  uint64 genesisHeight;
+  uint64 genesisTimestamp;
+  uint64 __reservedA1;
+  uint64 statusBits;
+  uint64 nextBlockId;
+  uint64 lastProposedAt;
+  uint64 avgBlockTime;
+  uint64 __avgGasLimit;
+  uint64 latestVerifiedHeight;
+  uint64 latestVerifiedId;
+  uint64 avgProofTime;
+  uint64 __reservedC1;
+  uint256[42] __gap;
+}
+```
+
+### TentativeState
+
+```solidity
+struct TentativeState {
+  mapping(address => bool) proposers;
+  mapping(address => bool) provers;
+  bool whitelistProposers;
+  bool whitelistProvers;
+  uint256[46] __gap;
+}
+```
+
+### saveProposedBlock
+
+```solidity
+function saveProposedBlock(struct LibData.State state, uint256 id, struct LibData.ProposedBlock blk) internal
+```
+
+### getProposedBlock
+
+```solidity
+function getProposedBlock(struct LibData.State state, uint256 id) internal view returns (struct LibData.ProposedBlock)
+```
+
+### getL2BlockHash
+
+```solidity
+function getL2BlockHash(struct LibData.State state, uint256 number) internal view returns (bytes32)
+```
+
+### getStateVariables
+
+```solidity
+function getStateVariables(struct LibData.State state) internal view returns (uint64 genesisHeight, uint64 latestVerifiedHeight, uint64 latestVerifiedId, uint64 nextBlockId)
+```
+
+### hashMetadata
+
+```solidity
+function hashMetadata(struct LibData.BlockMetadata meta) internal pure returns (bytes32)
+```
diff --git a/packages/website/docs/smart-contracts/L1/TkoToken.md b/packages/website/docs/smart-contracts/L1/TkoToken.md
@@ -2,7 +2,6 @@
 
 _This is Taiko's governance and fee token._
 
-
 ### Mint
 
 ```solidity

diff --git a/packages/website/docs/smart-contracts/L2/TaikoL2.md b/packages/website/docs/smart-contracts/L2/TaikoL2.md
@@ -1,17 +1,5 @@
 ## TaikoL2
 
-### l2Hashes
-
-```solidity
-mapping(uint256 => bytes32) l2Hashes
-```
-
-### l1Hashes
-
-```solidity
-mapping(uint256 => bytes32) l1Hashes
-```
-
 ### publicInputHash
 
 ```solidity

diff --git a/packages/website/docs/smart-contracts/bridge/Bridge.md b/packages/website/docs/smart-contracts/bridge/Bridge.md
@@ -5,12 +5,6 @@ which calls the library implementations. See {IBridge} for more details.
 
 _The code hash for the same address on L1 and L2 may be different._
 
-### state
-
-```solidity
-struct LibBridgeData.State state
-```
-
 ### MessageStatusChanged
 
 ```solidity

diff --git a/packages/website/docs/smart-contracts/bridge/EtherVault.md b/packages/website/docs/smart-contracts/bridge/EtherVault.md
@@ -2,18 +2,6 @@
 
 Vault that holds Ether.
 
-### authorizedAddrs
-
-```solidity
-mapping(address => bool) authorizedAddrs
-```
-
-### \_\_gap
-
-```solidity
-uint256[49] __gap
-```
-
 ### Authorized
 
 ```solidity

diff --git a/packages/website/docs/smart-contracts/bridge/IBridge.md b/packages/website/docs/smart-contracts/bridge/IBridge.md
@@ -22,7 +22,6 @@ struct Message {
   bytes data;
   string memo;
 }
-
 ```
 
 ### Context
@@ -33,7 +32,6 @@ struct Context {
   address sender;
   uint256 srcChainId;
 }
-
 ```
 
 ### SignalSent

diff --git a/packages/website/docs/smart-contracts/bridge/TokenVault.md b/packages/website/docs/smart-contracts/bridge/TokenVault.md
@@ -14,7 +14,6 @@ struct CanonicalERC20 {
   string symbol;
   string name;
 }
-
 ```
 
 ### isBridgedToken
@@ -35,12 +34,6 @@ mapping(address => struct TokenVault.CanonicalERC20) bridgedToCanonical
 mapping(uint256 => mapping(address => address)) canonicalToBridged
 ```
 
-### \_\_gap
-
-```solidity
-uint256[47] __gap
-```
-
 ### BridgedERC20Deployed
 
 ```solidity
@@ -140,15 +133,3 @@ invoking a message call._
 | from           | address                          | The source address.                                                                                                  |
 | to             | address                          | The destination address.                                                                                             |
 | amount         | uint256                          | The amount of tokens to be sent. 0 is a valid value.                                                                 |
-
-### \_getOrDeployBridgedToken
-
-```solidity
-function _getOrDeployBridgedToken(struct TokenVault.CanonicalERC20 canonicalToken) private returns (address)
-```
-
-### \_deployBridgedToken
-
-```solidity
-function _deployBridgedToken(struct TokenVault.CanonicalERC20 canonicalToken) private returns (address bridgedToken)
-```
diff --git a/packages/website/docs/smart-contracts/common/AddressResolver.md b/packages/website/docs/smart-contracts/common/AddressResolver.md
@@ -9,12 +9,6 @@ it uses an AddressManager to manage the name-to-address mapping.
 contract IAddressManager _addressManager
 ```
 
-### \_\_gap
-
-```solidity
-uint256[49] __gap
-```
-
 ### onlyFromNamed
 
 ```solidity
@@ -91,9 +85,3 @@ Returns the AddressManager's address.
 ```solidity
 function _init(address addressManager_) internal virtual
 ```
-
-### \_resolve
-
-```solidity
-function _resolve(uint256 chainId, string name) private view returns (address payable)
-```
diff --git a/packages/website/docs/smart-contracts/common/ConfigManager.md b/packages/website/docs/smart-contracts/common/ConfigManager.md
@@ -1,11 +1,5 @@
 ## ConfigManager
 
-### kv
-
-```solidity
-mapping(bytes32 => bytes) kv
-```
-
 ### Updated
 
 ```solidity

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml