ammend generated docs with solc's devdoc output

2 files changed, 63 insertions, 15 deletions

diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts
index 240fbbd75..a1ef32e79 100644
--- a/packages/sol-doc/src/solidity_doc_generator.ts
+++ b/packages/sol-doc/src/solidity_doc_generator.ts
@@ -117,10 +117,8 @@ function _genConstructorDoc(abiDefinition: ConstructorAbi, devdocIfExists: Devdo
         devdocIfExists,
     );
 
-    let comment;
-    // TODO: use methodSignature as the key to abiEntry.devdoc.methods, and
-    // from that object extract the "details" (comment) property
-    comment = `something from devdoc, using ${methodSignature} to find it`;
+    const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
+    // TODO: figure out why devdoc'd constructors don't get output by solc
 
     const constructorDoc: SolidityMethod = {
         isConstructor: true,
@@ -136,6 +134,26 @@ function _genConstructorDoc(abiDefinition: ConstructorAbi, devdocIfExists: Devdo
     return constructorDoc;
 }
 
+function _devdocMethodDetailsIfExist(
+    methodSignature: string,
+    devdocIfExists: DevdocOutput | undefined,
+): string | undefined {
+    let details;
+    if (!_.isUndefined(devdocIfExists)) {
+        const devdocMethodsIfExist = devdocIfExists.methods;
+        if (!_.isUndefined(devdocMethodsIfExist)) {
+            const devdocMethodIfExists = devdocMethodsIfExist[methodSignature];
+            if (!_.isUndefined(devdocMethodIfExists)) {
+                const devdocMethodDetailsIfExist = devdocMethodIfExists.details;
+                if (!_.isUndefined(devdocMethodDetailsIfExist)) {
+                    details = devdocMethodDetailsIfExist;
+                }
+            }
+        }
+    }
+    return details;
+}
+
 function _genMethodDoc(
     abiDefinition: MethodAbi | FallbackAbi,
     devdocIfExists: DevdocOutput | undefined,
@@ -147,10 +165,7 @@ function _genMethodDoc(
             ? { parameters: [], methodSignature: `${name}()` }
             : _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists);
 
-    let comment;
-    // TODO: use methodSignature as the key to abiEntry.devdoc.methods, and
-    // from that object extract the "details" (comment) property
-    comment = 'something from devdoc';
+    const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
 
     const returnType =
         abiDefinition.type === 'fallback'
@@ -205,9 +220,6 @@ function _genEventArgsDoc(args: DataItem[], devdocIfExists: DevdocOutput | undef
 
 /**
  * Extract documentation for each method paramater from @param params.
- * TODO: Then, use @param name, along with the types of the method
- * parameters, to form a method signature.  That signature is the key to
- * the method documentation held in @param devdocIfExists.
  */
 function _genMethodParamsDoc(
     name: string,
@@ -215,18 +227,37 @@ function _genMethodParamsDoc(
     devdocIfExists: DevdocOutput | undefined,
 ): { parameters: Parameter[]; methodSignature: string } {
     const parameters: Parameter[] = [];
+    let methodSignature = `${name}(`;
+
     for (const abiParam of abiParams) {
         const parameter: Parameter = {
             name: abiParam.name,
-            comment: '', // TODO: get from devdoc. see comment below.
+            comment: '',
             isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232
             type: { name: abiParam.type, typeDocType: TypeDocTypes.Intrinsic },
         };
         parameters.push(parameter);
+        methodSignature = `${methodSignature}${abiParam.type},`;
     }
-    // TODO: use methodSignature as the key to abiEntry.devdoc.methods, and
-    // from that object extract the "details" (comment) property
-    return { parameters, methodSignature: '' };
+
+    if (methodSignature.slice(-1) === ',') {
+        methodSignature = methodSignature.slice(0, -1);
+    }
+    methodSignature += ')';
+
+    if (!_.isUndefined(devdocIfExists)) {
+        const devdocMethodIfExists = devdocIfExists.methods[methodSignature];
+        if (!_.isUndefined(devdocMethodIfExists)) {
+            const devdocParamsIfExist = devdocMethodIfExists.params;
+            if (!_.isUndefined(devdocParamsIfExist)) {
+                for (const parameter of parameters) {
+                    parameter.comment = devdocParamsIfExist[parameter.name];
+                }
+            }
+        }
+    }
+
+    return { parameters, methodSignature };
 }
 
 function _genMethodReturnTypeDoc(
diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts
index 989f29320..7f11fcdfd 100644
--- a/packages/sol-doc/test/solidity_doc_generator_test.ts
+++ b/packages/sol-doc/test/solidity_doc_generator_test.ts
@@ -3,6 +3,8 @@ import * as _ from 'lodash';
 import * as chai from 'chai';
 import 'mocha';
 
+import { SolidityMethod } from '@0xproject/types';
+
 import { generateSolDocAsync } from '../src/solidity_doc_generator';
 
 import { chaiSetup } from './util/chai_setup';
@@ -55,5 +57,20 @@ describe('#SolidityDocGenerator', () => {
             throw new Error('events should never be undefined');
         }
         expect(doc.ERC20Basic.events.length).to.equal(erc20BasicEventCount);
+
+        let addAuthorizedAddressMethod: SolidityMethod | undefined;
+        for (const method of doc.TokenTransferProxy.methods) {
+            if (method.name === 'addAuthorizedAddress') {
+                addAuthorizedAddressMethod = method;
+            }
+        }
+        expect(
+            addAuthorizedAddressMethod,
+            `method addAuthorizedAddress not found in ${JSON.stringify(doc.TokenTransferProxy.methods)}`,
+        ).to.not.be.undefined();
+        const tokenTransferProxyAddAuthorizedAddressComment = 'Authorizes an address.';
+        expect((addAuthorizedAddressMethod as SolidityMethod).comment).to.equal(
+            tokenTransferProxyAddAuthorizedAddressComment,
+        );
     });
 });