Docs: Improved doc generation

.github/workflows/contract-tests.yml

@@ -38,3 +38,5 @@ jobs:
           HARDHAT_PLUGIN_ENS_DOMAIN: 'plugin.dao.eth'
           MANAGINGDAO_SUBDOMAIN: 'aragon-management'
         run: yarn run test
+      - name: Run solidity-docgen
+        run: yarn run docgen

.github/workflows/documentation-update.yml

@@ -22,6 +22,8 @@ jobs:
       - name: Generate Docs
         run: yarn run docgen
         working-directory: packages/contracts/
+      - name: Format with prettier
+        run: yarn run prettier 'packages/contracts/docs/osx/03-reference-guide/**/*.md' --write
       - name: Checkout builders-portal
         uses: actions/checkout@v3
         with:

packages/contracts/docs/templates/common.hbs

@@ -1,4 +1,4 @@
-{{h 2}} {{visibility}} {{toLowerCase type}} `{{name}}`
+{{h 2}} {{visibility}} {{toLowerCase type}} {{name}}
 
 {{{natspec.notice}}}
 
@@ -12,20 +12,20 @@
 | Input | Type | Description |
 |:----- | ---- | ----------- |
 {{#each params}}
-| {{name}} | {{type}} | {{{joinLines natspec}}} |
+| `{{{name}}}` | `{{{type}}}` | {{{joinLines natspec}}} |
 {{/each}}
 {{#if natspec.returns}}
 | **Output** | |
 {{#each returns}}
-| {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} |
+| {{#if name}} `{{name}}` {{else}} `{{@index}}` {{/if}} | `{{type}}` | {{{joinLines natspec}}} |
 {{/each}}
 {{/if}}
 {{else}}
 {{#if natspec.returns}}
 | Output | Type | Description |
 | ------ | ---- | ----------- |
 {{#each returns}}
-| {{#if name}}{{name}}{{else}}[{{@index}}]{{/if}} | {{type}} | {{{joinLines natspec}}} |
+| {{#if name}} `{{{name}}}` {{else}} `{{{@index}}}` {{/if}} | `{{type}}` | {{{joinLines natspec}}} |
 {{/each}}
 {{/if}}
 {{/if}}

packages/contracts/docs/templates/contract.hbs

@@ -1,8 +1,12 @@
-{{>common}}
+## Description
+
+{{{natspec.notice}}}
+
+{{{natspec.dev}}}
+
+## Implementation
 
 {{#each items}}
-{{#hsection}}
 {{>item}}
-{{/hsection}}
-
 {{/each}}
+<!--CONTRACT_END-->

packages/contracts/docs/templates/page.hbs

@@ -1,4 +1,3 @@
-## Aragon OSx
 
 {{#each items}}
 {{#hsection}}

packages/contracts/package.json

@@ -69,7 +69,7 @@
     "rollup-plugin-dts": "^4.2.0",
     "solhint": "^3.3.6",
     "solidity-coverage": "^0.8.2",
-    "solidity-docgen": "^0.6.0-beta.19",
+    "solidity-docgen": "^0.6.0-beta.35",
     "tmp-promise": "^3.0.3",
     "ts-node": "^8.1.0",
     "typechain": "^5.2.0",

packages/contracts/src/plugins/governance/majority-voting/IMajorityVoting.sol

@@ -7,7 +7,6 @@ import {IDAO} from "../../../core/dao/IDAO.sol";
 /// @title IMajorityVoting
 /// @author Aragon Association - 2022-2023
 /// @notice The interface of majority voting plugin.
-/// @dev This contract implements the `IMajorityVoting` interface.
 interface IMajorityVoting {
     /// @notice Vote options that a voter can chose from.
     /// @param None The default option state of a voter indicating the absence of from the vote. This option neither influences support nor participation.

packages/contracts/src/plugins/governance/majority-voting/MajorityVotingBase.sol

@@ -15,49 +15,48 @@ import {IMajorityVoting} from "./IMajorityVoting.sol";
 
 /// @title MajorityVotingBase
 /// @author Aragon Association - 2022-2023
-
 /// @notice The abstract implementation of majority voting plugins.
 ///
-/// #### Parameterization
+/// ### Parameterization
 ///
 /// We define two parameters
 /// $$\texttt{support} = \frac{N_\text{yes}}{N_\text{yes} + N_\text{no}} \in [0,1]$$
 /// and
 /// $$\texttt{participation} = \frac{N_\text{yes} + N_\text{no} + N_\text{abstain}}{N_\text{total}} \in [0,1],$$
-/// where $N_\text{yes}$, $N_\text{no}$, and $N_\text{abstain}$ are the yes, no, and abstain votes that have been cast and $N_\text{total}$ is the total voting power available at /// proposal creation time.
+/// where $N_\text{yes}$, $N_\text{no}$, and $N_\text{abstain}$ are the yes, no, and abstain votes that have been cast and $N_\text{total}$ is the total voting power available at proposal creation time.
 ///
-/// ##### Limit Values: Support Threshold & Minimum Participation
+/// #### Limit Values: Support Threshold & Minimum Participation
 ///
-/// Two limit values are associated with these parameters and decide if a proposal execution should be possible: $\texttt{supportThreshold} \in [0,1]$ and $\texttt{minParticipation} \in /// [0,1]$.
+/// Two limit values are associated with these parameters and decide if a proposal execution should be possible: $\texttt{supportThreshold} \in [0,1]$ and $\texttt{minParticipation} \in [0,1]$.
 ///
-/// For threshold values, $>$ comparison is used. This **does not** include the threshold value. E.g., for $\texttt{supportThreshold} = 50\%$, the criterion is fulfilled if there is at /// least one more yes than no votes ($N_\text{yes} = N_\text{no} + 1 $).
-/// For minimum values, $\ge$ comparison is used. This **does** include the minimum participation value. E.g., for $\texttt{minParticipation} = 40\%$ and $N_\text{total} = 10$, the /// criterion is fulfilled if 4 out of 10 votes were casted.
+/// For threshold values, $>$ comparison is used. This **does not** include the threshold value. E.g., for $\texttt{supportThreshold} = 50\%$, the criterion is fulfilled if there is at least one more yes than no votes ($N_\text{yes} = N_\text{no} + 1$).
+/// For minimum values, $\ge{}$ comparison is used. This **does** include the minimum participation value. E.g., for $\texttt{minParticipation} = 40\%$ and $N_\text{total} = 10$, the criterion is fulfilled if 4 out of 10 votes were casted.
 ///
 /// Majority voting implies that the support threshold is set with
 /// $$\texttt{supportThreshold} \ge 50\% .$$
 /// However, this is not enforced by the contract code and developers can make unsafe parameters and only the frontend will warn about bad parameter settings.
 ///
-/// #### Execution Criteria
+/// ### Execution Criteria
 ///
 /// After the vote is closed, two criteria decide if the proposal passes.
 ///
-/// ##### The Support Criterion
+/// #### The Support Criterion
 ///
 /// For a proposal to pass, the required ratio of yes and no votes must be met:
 /// $$(1- \texttt{supportThreshold}) \cdot N_\text{yes} > \texttt{supportThreshold} \cdot N_\text{no}.$$
 /// Note, that the inequality yields the simple majority voting condition for $\texttt{supportThreshold}=\frac{1}{2}$.
 ///
-/// ##### The Participation Criterion
+/// #### The Participation Criterion
 ///
 /// For a proposal to pass, the minimum voting power must have been cast:
 /// $$N_\text{yes} + N_\text{no} + N_\text{abstain} \ge \texttt{minVotingPower},$$
 /// where $\texttt{minVotingPower} = \texttt{minParticipation} \cdot N_\text{total}$.
 ///
-/// #### Vote Replacement Execution
+/// ### Vote Replacement Execution
 ///
 /// The contract allows votes to be replaced. Voters can vote multiple times and only the latest voteOption is tallied.
 ///
-/// #### Early Execution
+/// ### Early Execution
 ///
 /// This contract allows a proposal to be executed early, iff the vote outcome cannot change anymore by more people voting. Accordingly, vote replacement and early execution are /// mutually exclusive options.
 /// The outcome cannot change anymore iff the support threshold is met even if all remaining votes are no votes. We call this number the worst-case number of no votes and define it as

yarn.lock

@@ -9950,10 +9950,10 @@ solidity-ast@^0.4.15:
   resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.38.tgz#103e8340e871882e10cfb5c06fab9bf8dff4100a"
   integrity sha512-e7gT6g8l8M2rAzH648QA3/IihCNy/anFoWyChVD+T+zfX4FjXbT8AO2DB3wG1iEmIBib9/+vD+GvTElWWpdw+w==
 
-solidity-ast@^0.4.31:
-  version "0.4.35"
-  resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.35.tgz#82e064b14dc989338123264bde2235cad751f128"
-  integrity sha512-F5bTDLh3rmDxRmLSrs3qt3nvxJprWSEkS7h2KmuXDx7XTfJ6ZKVTV1rtPIYCqJAuPsU/qa8YUeFn7jdOAZcTPA==
+solidity-ast@^0.4.38:
+  version "0.4.46"
+  resolved "https://registry.yarnpkg.com/solidity-ast/-/solidity-ast-0.4.46.tgz#d0745172dced937741d07464043564e35b147c59"
+  integrity sha512-MlPZQfPhjWXqh7YxWcBGDXaPZIfMYCOHYoLEhGDWulNwEPIQQZuB7mA9eP17CU0jY/bGR4avCEUVVpvHtT2gbA==
 
 solidity-comments-extractor@^0.0.7:
   version "0.0.7"
@@ -9986,13 +9986,13 @@ solidity-coverage@^0.8.2:
     shelljs "^0.8.3"
     web3-utils "^1.3.6"
 
-solidity-docgen@^0.6.0-beta.19:
-  version "0.6.0-beta.19"
-  resolved "https://registry.yarnpkg.com/solidity-docgen/-/solidity-docgen-0.6.0-beta.19.tgz#6b5f0c6fae4f61913511ff3db31b8ef488db03fa"
-  integrity sha512-EEaDg3pm3yJmE+0ML8i5Ezej/nfVncwuDijFogiPTIc44kA23eLbLD8jZ0tMeGlmjyV8eOOQqukAA35tE6rORQ==
+solidity-docgen@^0.6.0-beta.35:
+  version "0.6.0-beta.35"
+  resolved "https://registry.yarnpkg.com/solidity-docgen/-/solidity-docgen-0.6.0-beta.35.tgz#174d7fe54efa8b10f7d3cbe0dfc40e52e11bf867"
+  integrity sha512-9QdwK1THk/MWIdq1PEW/6dvtND0pUqpFTsbKwwU9YQIMYuRhH1lek9SsgnsGGYtdJ0VTrXXcVT30q20a8Y610A==
   dependencies:
     handlebars "^4.7.7"
-    solidity-ast "^0.4.31"
+    solidity-ast "^0.4.38"
 
 source-map-support@^0.5.13, source-map-support@^0.5.17, source-map-support@^0.5.19, source-map-support@^0.5.20:
   version "0.5.21"