Feat/update natspec and doc

.gitignore

@@ -14,6 +14,8 @@ packages/subgraph/imported
 packages/subgraph/generated
 packages/subgraph/tests/.bin
 
+docs
+
 # files
 *.env
 *.log

packages/contracts/hardhat.config.ts

@@ -20,6 +20,7 @@ import {
 import type {NetworkUserConfig} from 'hardhat/types';
 import {resolve} from 'path';
 import 'solidity-coverage';
+import 'solidity-docgen';
 
 const dotenvConfigPath: string = process.env.DOTENV_CONFIG_PATH || '../../.env';
 dotenvConfig({path: resolve(__dirname, dotenvConfigPath), override: true});
@@ -178,6 +179,13 @@ const config: HardhatUserConfig = {
     outDir: 'typechain',
     target: 'ethers-v5',
   },
+  docgen: {
+    outputDir: 'docs',
+    theme: 'markdown',
+    pages: 'files',
+    collapseNewlines: true,
+    exclude: ['test', 'mocks'],
+  },
 };
 
 export default config;

packages/contracts/package.json

@@ -8,6 +8,7 @@
     "lint:sol": "cd ../../ && yarn run lint:contracts:sol",
     "lint:ts": "cd ../../ && yarn run lint:contracts:ts",
     "test": "hardhat test",
+    "docgen": "hardhat docgen",
     "typechain": "cross-env TS_NODE_TRANSPILE_ONLY=true hardhat typechain",
     "clean": "rimraf ./artifacts ./cache ./coverage ./typechain ./types ./coverage.json && yarn typechain"
   },
@@ -38,11 +39,12 @@
     "@types/chai": "^4.3.4",
     "@types/mocha": "^10.0.0",
     "@types/node": "^18.11.9",
+    "solidity-docgen": "^0.6.0-beta.36",
     "chai": "^4.3.7",
     "cross-env": "^7.0.3",
     "dotenv": "^16.3.1",
     "ethers": "5.7.2",
-    "hardhat": "^2.13.1",
+    "hardhat": "^2.22.15",
     "hardhat-deploy": "^0.11.26",
     "hardhat-gas-reporter": "^1.0.9",
     "ipfs-http-client": "^51.0.0",

packages/contracts/src/ERC20/governance/GovernanceWrappedERC20.sol

@@ -31,7 +31,7 @@ import {IGovernanceWrappedERC20} from "./IGovernanceWrappedERC20.sol";
 /// `withdrawFor`, which  burns the wrapped [ERC-20](https://eips.ethereum.org/EIPS/eip-20) tokens and
 /// safely transfers the underlying tokens back to the owner.
 /// @dev This contract intentionally has no public mint functionality because this is the
-/// responsibility of the underlying [ERC-20](https://eips.ethereum.org/EIPS/eip-20) token contract.
+///      responsibility of the underlying [ERC-20](https://eips.ethereum.org/EIPS/eip-20) token contract.
 /// @custom:security-contact [email protected]
 contract GovernanceWrappedERC20 is
     IGovernanceWrappedERC20,

packages/contracts/src/ERC20/governance/IGovernanceWrappedERC20.sol

@@ -5,7 +5,7 @@ pragma solidity ^0.8.8;
 /// @title IGovernanceWrappedERC20
 /// @author Aragon X
 /// @notice An interface for the token wrapping contract wrapping existing
-/// [ERC-20](https://eips.ethereum.org/EIPS/eip-20) tokens.
+///         [ERC-20](https://eips.ethereum.org/EIPS/eip-20) tokens.
 /// @custom:security-contact [email protected]
 interface IGovernanceWrappedERC20 {
     /// @notice Deposits an amount of underlying token

packages/contracts/src/IMajorityVoting.sol

@@ -3,13 +3,13 @@
 pragma solidity ^0.8.8;
 
 /// @title IMajorityVoting
-/// @author Aragon X - 2022-2023
+/// @author Aragon X - 2022-2024
 /// @notice The interface of majority voting plugin.
 /// @custom:security-contact [email protected]
 interface IMajorityVoting {
     /// @notice Vote options that a voter can chose from.
     /// @param None The default option state of a voter indicating the absence from the vote.
-    /// This option neither influences support nor participation.
+    ///     This option neither influences support nor participation.
     /// @param Abstain This option does not influence the support but counts towards participation.
     /// @param Yes This option increases the support and counts towards participation.
     /// @param No This option decreases the support and counts towards participation.
@@ -36,7 +36,7 @@ interface IMajorityVoting {
     /// @return The support threshold parameter.
     function supportThreshold() external view returns (uint32);
 
-    /// @notice Returns the min approval value stored configured.
+    /// @notice Returns the configured minimum approval value.
     /// @return The minimal approval value.
     function minApproval() external view returns (uint256);
 
@@ -45,43 +45,43 @@ interface IMajorityVoting {
     function minParticipation() external view returns (uint32);
 
     /// @notice Checks if the support value defined as:
-    /// $$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes}+N_\text{no}}$$
-    /// for a proposal vote is greater than the support threshold.
+    ///     $$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes}+N_\text{no}}$$
+    ///     for a proposal is greater than the support threshold.
     /// @param _proposalId The ID of the proposal.
     /// @return Returns `true` if the  support is greater than the support threshold and `false` otherwise.
     function isSupportThresholdReached(uint256 _proposalId) external view returns (bool);
 
     /// @notice Checks if the worst-case support value defined as:
-    /// $$\texttt{worstCaseSupport} = \frac{N_\text{yes}}{ N_\text{total}-N_\text{abstain}}$$
-    /// for a proposal vote is greater than the support threshold.
+    ///     $$\texttt{worstCaseSupport} = \frac{N_\text{yes}}{ N_\text{total}-N_\text{abstain}}$$
+    ///     for a proposal is greater than the support threshold.
     /// @param _proposalId The ID of the proposal.
     /// @return Returns `true` if the worst-case support is greater than the support threshold and `false` otherwise.
     function isSupportThresholdReachedEarly(uint256 _proposalId) external view returns (bool);
 
     /// @notice Checks if the participation value defined as:
-    /// $$\texttt{participation} = \frac{N_\text{yes}+N_\text{no}+N_\text{abstain}}{N_\text{total}}$$
-    /// for a proposal vote is greater or equal than the minimum participation value.
+    ///     $$\texttt{participation} = \frac{N_\text{yes}+N_\text{no}+N_\text{abstain}}{N_\text{total}}$$
+    ///     for a proposal is greater or equal than the minimum participation value.
     /// @param _proposalId The ID of the proposal.
-    /// @return Returns `true` if the participation is greater than the minimum participation and `false` otherwise.
+    /// @return Returns `true` if the participation is greater or equal than the minimum participation,
+    ///     and `false` otherwise.
     function isMinParticipationReached(uint256 _proposalId) external view returns (bool);
 
     /// @notice Checks if the min approval value defined as:
-    ///$$\texttt{minApproval} = \frac{N_\text{yes}}{N_\text{total}}$$
-    /// for a proposal vote is greater or equal than the minimum approval value.
+    ///     $$\texttt{minApproval} = \frac{N_\text{yes}}{N_\text{total}}$$
+    ///     for a proposal is greater or equal than the minimum approval value.
     /// @param _proposalId The ID of the proposal.
-    /// @return Returns `true` if the participation is greater than the minimum participation and `false` otherwise.
+    /// @return Returns `true` if the approvals is greater or equal than the minimum approval and `false` otherwise.
     function isMinApprovalReached(uint256 _proposalId) external view returns (bool);
 
-    /// @notice Checks if an account can participate on a proposal vote. This can be because the vote
+    /// @notice Checks if an account can participate on a proposal. This can be because the vote
     /// - has not started,
     /// - has ended,
     /// - was executed, or
     /// - the voter doesn't have voting powers.
     /// @param _proposalId The proposal Id.
     /// @param _account The account address to be checked.
-    /// @param  _voteOption Whether the voter abstains, supports or opposes the proposal.
+    /// @param _voteOption Whether the voter abstains, supports or opposes the proposal.
     /// @return Returns true if the account is allowed to vote.
-    /// @dev The function assumes the queried proposal exists.
     function canVote(
         uint256 _proposalId,
         address _account,
@@ -93,20 +93,21 @@ interface IMajorityVoting {
     /// @return True if the proposal can be executed, false otherwise.
     function canExecute(uint256 _proposalId) external view returns (bool);
 
-    /// @notice Votes for a vote option and, optionally, executes the proposal.
+    /// @notice Votes on a proposal and, optionally, executes the proposal.
     /// @dev `_voteOption`, 1 -> abstain, 2 -> yes, 3 -> no
     /// @param _proposalId The ID of the proposal.
     /// @param _voteOption The chosen vote option.
     /// @param _tryEarlyExecution If `true`,  early execution is tried after the vote cast.
-    /// The call does not revert if early execution is not possible.
+    ///     The call does not revert if early execution is not possible.
     function vote(uint256 _proposalId, VoteOption _voteOption, bool _tryEarlyExecution) external;
 
     /// @notice Executes a proposal.
     /// @param _proposalId The ID of the proposal to be executed.
     function execute(uint256 _proposalId) external;
 
     /// @notice Returns whether the account has voted for the proposal.
-    /// Note, that this does not check if the account has voting power.
+    /// @dev May return `none` if the `_proposalId` does not exist,
+    ///      or the `_account` does not have voting power.
     /// @param _proposalId The ID of the proposal.
     /// @param _account The account address to be checked.
     /// @return The vote option cast by a voter for a certain proposal.