Add devdocs to generated contract wrappers (#2013)

* first pass at including doc comments

* incorporate suggestions for method comments; add devdoc to dummy contract

* better formatting and persist generated docs as circleci build artifacts

* store artifacts properly

* hanging indent for method params

.circleci/config.yml

@@ -37,6 +37,8 @@ jobs:
                   path: ~/repo/packages/python-contract-wrappers/generated
             - store_artifacts:
                   path: ~/repo/packages/abi-gen/test-cli/output
+            - store_artifacts:
+                  path: ~/repo/packages/abi-gen-wrappers/generated_docs
     build-website:
         resource_class: medium+
         docker:

packages/abi-gen-templates/contract.handlebars

@@ -51,6 +51,11 @@ export enum {{contractName}}Events {
 // tslint:disable-next-line:class-name
 export class {{contractName}}Contract extends BaseContract {
 {{#each methods}}
+    {{#if this.devdoc.details}}
+    /**
+     * {{formatDocstringForMethodTs this.devdoc.details}}
+     */
+     {{/if}}
     {{#this.constant}}
     {{> call contractName=../contractName}}
     {{/this.constant}}
@@ -153,11 +158,11 @@ export class {{contractName}}Contract extends BaseContract {
     }{{#if events}}
     /**
      * Subscribe to an event type emitted by the {{contractName}} contract.
-     * @param   eventName           The {{contractName}} contract event you would like to subscribe to.
-     * @param   indexFilterValues   An object where the keys are indexed args returned by the event and
-     *                              the value is the value you are interested in. E.g `{maker: aUserAddressHex}`
-     * @param   callback            Callback that gets called when a log is added/removed
-     * @param   isVerbose           Enable verbose subscription warnings (e.g recoverable network issues encountered)
+     * @param eventName The {{contractName}} contract event you would like to subscribe to.
+     * @param indexFilterValues An object where the keys are indexed args returned by the event and
+     * the value is the value you are interested in. E.g `{maker: aUserAddressHex}`
+     * @param callback Callback that gets called when a log is added/removed
+     * @param isVerbose Enable verbose subscription warnings (e.g recoverable network issues encountered)
      * @return Subscription token used later to unsubscribe
      */
     public subscribe<ArgsType extends {{contractName}}EventArgs>(
@@ -183,7 +188,7 @@ export class {{contractName}}Contract extends BaseContract {
     }
     /**
      * Cancel a subscription
-     * @param   subscriptionToken Subscription token returned by `subscribe()`
+     * @param subscriptionToken Subscription token returned by `subscribe()`
      */
     public unsubscribe(subscriptionToken: string): void {
         this._subscriptionManager.unsubscribe(subscriptionToken);
@@ -196,11 +201,11 @@ export class {{contractName}}Contract extends BaseContract {
     }
     /**
      * Gets historical logs without creating a subscription
-     * @param   eventName           The {{contractName}} contract event you would like to subscribe to.
-     * @param   blockRange          Block range to get logs from.
-     * @param   indexFilterValues   An object where the keys are indexed args returned by the event and
-     *                              the value is the value you are interested in. E.g `{_from: aUserAddressHex}`
-     * @return  Array of logs that match the parameters
+     * @param eventName The {{contractName}} contract event you would like to subscribe to.
+     * @param blockRange Block range to get logs from.
+     * @param indexFilterValues An object where the keys are indexed args returned by the event and
+     * the value is the value you are interested in. E.g `{_from: aUserAddressHex}`
+     * @return Array of logs that match the parameters
      */
     public async getLogsAsync<ArgsType extends {{contractName}}EventArgs>(
         eventName: {{contractName}}Events,

packages/abi-gen-templates/partials/callAsync.handlebars

@@ -1,3 +1,12 @@
+/**
+ * Sends a read-only call to the contract method. Returns the result that would happen if one were to send an 
+ * Ethereum transaction to this method, given the current state of the blockchain. Calls do not cost gas
+ * since they don't modify state.
+{{> params_docstring inputs=inputs docstrings=devdoc.params}}
+{{#if devdoc.return}}
+ * @returns {{devdoc.return}}
+{{/if}}
+ */
 async callAsync(
 {{> typed_params inputs=inputs}}
     callData: Partial<CallData> = {},
@@ -34,6 +43,12 @@ async callAsync(
     // tslint:enable boolean-naming
     return result;
 },
+/**
+ * Returns the ABI encoded transaction data needed to send an Ethereum transaction calling this method. Before
+ * sending the Ethereum tx, this encoded tx data can first be sent to a separate signing service or can be used
+ * to create a 0x transaction (see protocol spec for more details).
+{{> params_docstring inputs=inputs docstrings=devdoc.params}}
+ */
 getABIEncodedTransactionData(
     {{> typed_params inputs=inputs}}
     ): string {

packages/abi-gen-templates/partials/params_docstring.handlebars

@@ -0,0 +1,5 @@
+{{#each inputs}}
+    {{#if (getDocstringForParamTs name ../docstrings)}}
+ {{formatDocstringForParamTs name (getDocstringForParamTs name ../docstrings)}}
+    {{/if}}
+{{/each}}

packages/abi-gen-templates/partials/tx.handlebars

@@ -1,4 +1,11 @@
 public {{languageSpecificName}} = {
+    /**
+     * Sends an Ethereum transaction executing this method with the supplied parameters. This is a read/write
+     * Ethereum operation and will cost gas.
+    {{> params_docstring inputs=inputs docstrings=devdoc.params}}
+     * @param txData Additional data for transaction
+     * @returns The hash of the transaction
+     */
     async sendTransactionAsync(
     {{> typed_params inputs=inputs}}
     txData?: Partial<TxData> | undefined,
@@ -27,6 +34,14 @@ public {{languageSpecificName}} = {
     const txHash = await self._web3Wrapper.sendTransactionAsync(txDataWithDefaults);
     return txHash;
     },
+    /**
+     * Sends an Ethereum transaction and waits until the transaction has been successfully mined without reverting.
+     * If the transaction was mined, but reverted, an error is thrown.
+    {{> params_docstring inputs=inputs docstrings=devdoc.params}}
+     * @param txData Additional data for transaction
+     * @param pollingIntervalMs Interval at which to poll for success
+     * @returns A promise that resolves when the transaction is successful
+     */
     awaitTransactionSuccessAsync(
     {{> typed_params inputs=inputs}}
         txData?: Partial<TxData>,
@@ -54,6 +69,12 @@ public {{languageSpecificName}} = {
         })(),
     );
     },
+    /**
+     * Estimates the gas cost of sending an Ethereum transaction calling this method with these arguments.
+    {{> params_docstring inputs=inputs docstrings=devdoc.params}}
+     * @param txData Additional data for transaction
+     * @returns The hash of the transaction
+     */
     async estimateGasAsync(
     {{> typed_params inputs=inputs}}
         txData?: Partial<TxData> | undefined,

packages/abi-gen-wrappers/README.md

@@ -71,3 +71,9 @@ yarn lint
 ```bash
 yarn test
 ```
+
+### Documentation
+
+Documentation for this package is generated by TypeDoc, using the Solidity source code for 0x contracts. Each contract corresponds to one global-level module, which contains relevant enums and interfaces for its events and structs. Most significantly, each module exports a class, `<ContractName>Contract`, e.g. `ExchangeContract`, which implements helper methods for all the functions defined in the corresponding contract.
+
+A convention to note is that these contract-specific helper methods are defined as _object literals_, which are separated from methods in the generated documentation. Each contract method has a number of sub-methods, e.g. `sendTransactionAsync`, or `estimateGasAsync`, which are documented separately. This is an example of an expected method call signature: `exchangeContractInstance.fillOrder.sendTransactionAsync(...arguments)`.

packages/abi-gen-wrappers/package.json

@@ -10,15 +10,16 @@
         "test": "test"
     },
     "scripts": {
-        "build": "yarn pre_build && tsc -b",
+        "build": "yarn pre_build && tsc -b && yarn docs",
         "build:ci": "yarn build",
         "lint": "tslint --format stylish --project .",
         "fix": "tslint --fix --format stylish --project .",
         "pre_build": "yarn generate_contract_wrappers && yarn prettier_contract_wrappers",
         "prettier": "prettier --write src/**/* --config ../../.prettierrc",
         "prettier_contract_wrappers": "prettier --write src/generated-wrappers/* --config ../../.prettierrc",
         "clean": "shx rm -rf lib src/generated-wrappers",
-        "generate_contract_wrappers": "abi-gen --abis  ${npm_package_config_abis} --template ../../node_modules/@0x/abi-gen-templates/contract.handlebars --partials '../../node_modules/@0x/abi-gen-templates/partials/**/*.handlebars' --output src/generated-wrappers --backend ethers"
+        "generate_contract_wrappers": "abi-gen --abis  ${npm_package_config_abis} --template ../../node_modules/@0x/abi-gen-templates/contract.handlebars --partials '../../node_modules/@0x/abi-gen-templates/partials/**/*.handlebars' --output src/generated-wrappers --backend ethers",
+        "docs": "typedoc --excludePrivate --excludeExternals --target ES5 --tsconfig typedoc-tsconfig.json --out generated_docs ./src/generated-wrappers/*"
     },
     "config": {
         "abis": "../contract-artifacts/artifacts/@(AssetProxyOwner|DutchAuction|DummyERC20Token|DummyERC721Token|ERC20Proxy|ERC20Token|ERC721Proxy|ERC721Token|Exchange|Forwarder|IAssetProxy|IValidator|IWallet|MultiAssetProxy|OrderValidator|WETH9|ZRXToken|Coordinator|CoordinatorRegistry|EthBalanceChecker).json"