first pass at including doc comments

0xProject · Jul 30, 2019 · fe579be · fe579be
1 parent 46384ce
commit fe579be
Show file tree

Hide file tree

Showing 30 changed files with 4,332 additions and 1 deletion.
diff --git a/packages/abi-gen-templates/contract.handlebars b/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}}

diff --git a/packages/abi-gen-templates/partials/callAsync.handlebars b/packages/abi-gen-templates/partials/callAsync.handlebars
@@ -1,3 +1,10 @@
+/**
+ * Calls the method
+{{> 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
+{{> params_docstring inputs=inputs docstrings=devdoc.params}}
+ */
 getABIEncodedTransactionData(
     {{> typed_params inputs=inputs}}
     ): string {

diff --git a/packages/abi-gen-templates/partials/params_docstring.handlebars b/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}}
diff --git a/packages/abi-gen-templates/partials/tx.handlebars b/packages/abi-gen-templates/partials/tx.handlebars
@@ -1,4 +1,10 @@
 public {{languageSpecificName}} = {
+    /**
+     * Sends the transaction
+    {{> 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 the transaction and wait for it to succeed
+    {{> 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}} = {
         })(),
     );
     },
+    /**
+     * Estimate gas to send the transaction
+    {{> 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,

diff --git a/packages/abi-gen-wrappers/README.md b/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)`.
diff --git a/packages/abi-gen-wrappers/package.json b/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"