Add devdocs to generated contract wrappers

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}}

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

@@ -1,3 +1,10 @@
+/**
+ * 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 +41,11 @@ async callAsync(
     // tslint:enable boolean-naming
     return result;
 },
+
+/**
+ * Returns the ABI encoded transaction data needed to send an Ethereum tx 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)}}
+ * @param {{name}}         {{getDocstringForParamTs name ../docstrings}}
+    {{/if}}
+{{/each}}

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

@@ -1,4 +1,10 @@
 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 +33,13 @@ 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 +67,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,8 @@ yarn lint
 ```bash
 yarn test
 ```
+
+### Reading 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

@@ -18,7 +18,8 @@
         "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"