Generate (complete) solidity docs (#2391)

* `@0x/sol-doc`: New doc generator.

* `@0x/sol-compiler`: Be more tolerant of AST-only compilation targets.

* `@0x/contracts-exchange`: Add more devdoc comments.
`@0x/contracts-exchange-libs`: Add more devdoc comments.

* `@0x/sol-doc`: Update package script.

* `@0x/sol-doc`: Remove unused files and update package scripts to be easier to configure.

* Add more devdocs to contracts.

* `@0x/sol-doc`: Remove doc artifacts.

* `@0x/sol-doc`: Add `.gitignore` and `.npmignore`.

* `@0x/contracts-exchange`: Fix compilation errors.

* Fix more broken contracts.

* `@0x/contracts-erc20-bridge-sampler`: Fix failing tests.

* `@0x/contracts-asset-proxy`: Remove accidentally introduced hackathion file (lol).

* `@0x/sol-doc`: Prevent some inherited contracts from being included in docs unintentionally.

* `@0x/sol-doc`: Rename test file.

* `@0x/contracts-exchange`: Update `orderEpoch` devdoc.

* `@0x/sol-doc`: Tweak event and function docs.

* Update CODEOWNERS.

* `@0x/sol-doc` Tweak function md generation.

* `@0x/sol-doc`: add `transformDocs()` tests.

* `@0x/sol-doc`: add `extract_docs` tests.

* `@0x/sol-doc` Fix linter errors.

* `@0x/contracts-erc20-bridge-sampler`: Fix broken `ERC20BridgeSampler.sol` compile.

* `@0x/sol-doc` Fix mismatched `dev-utils` dep version.

* `@0x/sol-doc`: Add `gen_md` tests.

* `@0x/sol-doc`: Remove `fs.promises` calls.

* `@0x/sol-doc`: Fix linter errors.

* `@0x/sol-doc`: Export all relevant types and functions.

Co-authored-by: Lawrence Forman <me@merklejerk.com>

contracts/staking/compiler.json

@@ -14,6 +14,7 @@
             "*": {
                 "*": [
                     "abi",
+                    "devdoc",
                     "evm.bytecode.object",
                     "evm.bytecode.sourceMap",
                     "evm.deployedBytecode.object",

contracts/staking/contracts/src/StakingProxy.sol

@@ -26,6 +26,7 @@ import "./interfaces/IStorageInit.sol";
 import "./interfaces/IStakingProxy.sol";
 
 
+/// #dev The 0x Staking contract.
 contract StakingProxy is
     IStakingProxy,
     MixinStorage,

contracts/staking/contracts/src/immutable/MixinStorage.sol

@@ -51,19 +51,23 @@ contract MixinStorage is
     // tracking Pool Id, a unique identifier for each staking pool.
     bytes32 public lastPoolId;
 
-    // mapping from Maker Address to Pool Id of maker
+    /// @dev Mapping from Maker Address to pool Id of maker
+    /// @param 0 Maker address.
+    /// @return 0 The pool ID.
     mapping (address => bytes32) public poolIdByMaker;
 
     // mapping from Pool Id to Pool
     mapping (bytes32 => IStructs.Pool) internal _poolById;
 
-    // mapping from PoolId to balance of members
+    /// @dev mapping from pool ID to reward balance of members
+    /// @param 0 Pool ID.
+    /// @return 0 The total reward balance of members in this pool.
     mapping (bytes32 => uint256) public rewardsByPoolId;
 
-    // current epoch
+    // The current epoch.
     uint256 public currentEpoch;
 
-    // current epoch start time
+    // The current epoch start time.
     uint256 public currentEpochStartTimeInSeconds;
 
     // mapping from Pool Id to Epoch to Reward Ratio
@@ -72,7 +76,9 @@ contract MixinStorage is
     // mapping from Pool Id to Epoch
     mapping (bytes32 => uint256) internal _cumulativeRewardsByPoolLastStored;
 
-    // registered 0x Exchange contracts
+    /// @dev Registered 0x Exchange contracts, capable of paying protocol fees.
+    /// @param 0 The address to check.
+    /// @return 0 Whether the address is a registered exchange.
     mapping (address => bool) public validExchanges;
 
     /* Tweakable parameters */
@@ -95,11 +101,16 @@ contract MixinStorage is
     /* State for finalization */
 
     /// @dev Stats for each pool that generated fees with sufficient stake to earn rewards.
-    ///      See `_minimumPoolStake` in MixinParams.
+    ///      See `_minimumPoolStake` in `MixinParams`.
+    /// @param 0 Pool ID.
+    /// @param 1 Epoch number.
+    /// @return 0 Pool fee stats.
     mapping (bytes32 => mapping (uint256 => IStructs.PoolStats)) public poolStatsByEpoch;
 
     /// @dev Aggregated stats across all pools that generated fees with sufficient stake to earn rewards.
     ///      See `_minimumPoolStake` in MixinParams.
+    /// @param 0 Epoch number.
+    /// @return 0 Reward computation stats.
     mapping (uint256 => IStructs.AggregatedStats) public aggregatedStatsByEpoch;
 
     /// @dev The WETH balance of this contract that is reserved for pool reward payouts.

contracts/staking/contracts/src/interfaces/IStructs.sol

@@ -50,9 +50,9 @@ interface IStructs {
     /// @dev Encapsulates a balance for the current and next epochs.
     /// Note that these balances may be stale if the current epoch
     /// is greater than `currentEpoch`.
-    /// @param currentEpoch the current epoch
-    /// @param currentEpochBalance balance in the current epoch.
-    /// @param nextEpochBalance balance in `currentEpoch+1`.
+    /// @param currentEpoch The current epoch
+    /// @param currentEpochBalance Balance in the current epoch.
+    /// @param nextEpochBalance Balance in `currentEpoch+1`.
     struct StoredBalance {
         uint64 currentEpoch;
         uint96 currentEpochBalance;
@@ -68,7 +68,7 @@ interface IStructs {
     }
 
     /// @dev Info used to describe a status.
-    /// @param status of the stake.
+    /// @param status Status of the stake.
     /// @param poolId Unique Id of pool. This is set when status=DELEGATED.
     struct StakeInfo {
         StakeStatus status;
@@ -76,15 +76,15 @@ interface IStructs {
     }
 
     /// @dev Struct to represent a fraction.
-    /// @param numerator of fraction.
-    /// @param denominator of fraction.
+    /// @param numerator Numerator of fraction.
+    /// @param denominator Denominator of fraction.
     struct Fraction {
         uint256 numerator;
         uint256 denominator;
     }
 
     /// @dev Holds the metadata for a staking pool.
-    /// @param operator of the pool.
+    /// @param operator Operator of the pool.
     /// @param operatorShare Fraction of the total balance owned by the operator, in ppm.
     struct Pool {
         address operator;

contracts/staking/contracts/src/stake/MixinStake.sol

@@ -31,7 +31,7 @@ contract MixinStake is
 
     /// @dev Stake ZRX tokens. Tokens are deposited into the ZRX Vault.
     ///      Unstake to retrieve the ZRX. Stake is in the 'Active' status.
-    /// @param amount of ZRX to stake.
+    /// @param amount Amount of ZRX to stake.
     function stake(uint256 amount)
         external
     {
@@ -56,7 +56,7 @@ contract MixinStake is
     /// @dev Unstake. Tokens are withdrawn from the ZRX Vault and returned to
     ///      the staker. Stake must be in the 'undelegated' status in both the
     ///      current and next epoch in order to be unstaked.
-    /// @param amount of ZRX to unstake.
+    /// @param amount Amount of ZRX to unstake.
     function unstake(uint256 amount)
         external
     {
@@ -99,9 +99,9 @@ contract MixinStake is
     /// @dev Moves stake between statuses: 'undelegated' or 'delegated'.
     ///      Delegated stake can also be moved between pools.
     ///      This change comes into effect next epoch.
-    /// @param from status to move stake out of.
-    /// @param to status to move stake into.
-    /// @param amount of stake to move.
+    /// @param from Status to move stake out of.
+    /// @param to Status to move stake into.
+    /// @param amount Amount of stake to move.
     function moveStake(
         IStructs.StakeInfo calldata from,
         IStructs.StakeInfo calldata to,