transform solc's ABI output into doc types

3 files changed, 284 insertions, 66 deletions

diff --git a/packages/sol-doc/src/index.ts b/packages/sol-doc/src/index.ts
index dc88fae90..03f3c9de6 100644
--- a/packages/sol-doc/src/index.ts
+++ b/packages/sol-doc/src/index.ts
@@ -1 +1 @@
-export { SolidityDocGenerator } from './solidity_doc_generator';
+export { generateSolDocAsync } from './solidity_doc_generator';
diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts
index 95c89b2e5..312124ca1 100644
--- a/packages/sol-doc/src/solidity_doc_generator.ts
+++ b/packages/sol-doc/src/solidity_doc_generator.ts
@@ -1,76 +1,252 @@
 import * as _ from 'lodash';
 
-import { MethodAbi } from 'ethereum-types';
+import {
+    AbiDefinition,
+    ConstructorAbi,
+    DataItem,
+    DevdocOutput,
+    EventAbi,
+    FallbackAbi,
+    MethodAbi,
+    StandardContractOutput,
+} from 'ethereum-types';
 
 import { Compiler, CompilerOptions } from '@0xproject/sol-compiler';
-import { DocAgnosticFormat } from '@0xproject/types';
+import {
+    DocAgnosticFormat,
+    DocSection,
+    Event,
+    EventArg,
+    Parameter,
+    SolidityMethod,
+    Type,
+    TypeDocTypes,
+} from '@0xproject/types';
 import { logUtils } from '@0xproject/utils';
 
 /**
- * Compiles solidity files to both their ABI and devdoc outputs, and transforms
- * those outputs into the types that feed into documentation generation tools.
+ * Invoke the Solidity compiler and transform its ABI and devdoc outputs into
+ * the types that are used as input to documentation generation tools.
+ * @param contractsToCompile list of contracts for which to generate doc objects
+ * @param contractsDir the directory in which to find the `contractsToCompile` as well as their dependencies.
+ * @return doc object for use with documentation generation tools.
  */
-export class SolidityDocGenerator {
-    private readonly _compilerOptions: CompilerOptions;
-    /**
-     * Instantiate the generator.
-     * @param contractsDir the directory in which to find the contracts to be compiled
-     */
-    constructor(contractsDir: string) {
-        // instantiate sol-compiler, passing in options to say we want abi and devdoc
-        this._compilerOptions = {
-            contractsDir,
-            contracts: '*',
-            compilerSettings: {
-                outputSelection: {
-                    ['*']: {
-                        ['*']: ['abi', 'devdoc'],
-                    },
+export async function generateSolDocAsync(
+    contractsToCompile: string[],
+    contractsDir: string,
+): Promise<DocAgnosticFormat> {
+    const doc: DocAgnosticFormat = {};
+
+    const compilerOptions = _makeCompilerOptions(contractsToCompile, contractsDir);
+    const compiler = new Compiler(compilerOptions);
+    const compilerOutputs = await compiler.getCompilerOutputsAsync();
+    for (const compilerOutput of compilerOutputs) {
+        const contractFileNames = _.keys(compilerOutput.contracts);
+        for (const contractFileName of contractFileNames) {
+            const contractNameToOutput = compilerOutput.contracts[contractFileName];
+
+            const contractNames = _.keys(contractNameToOutput);
+            for (const contractName of contractNames) {
+                const compiledContract = contractNameToOutput[contractName];
+                if (_.isUndefined(compiledContract.abi)) {
+                    throw new Error('compiled contract did not contain ABI output');
+                }
+                doc[contractName] = _genDocSection(compiledContract);
+            }
+        }
+    }
+
+    return doc;
+}
+
+function _makeCompilerOptions(contractsToCompile: string[], contractsDir: string): CompilerOptions {
+    const compilerOptions: CompilerOptions = {
+        contractsDir,
+        contracts: '*',
+        compilerSettings: {
+            outputSelection: {
+                ['*']: {
+                    ['*']: ['abi', 'devdoc'],
                 },
             },
-        };
+        },
+    };
+
+    const shouldOverrideCatchAllContractsConfig = !_.isUndefined(contractsToCompile);
+    if (shouldOverrideCatchAllContractsConfig) {
+        compilerOptions.contracts = contractsToCompile;
     }
-    /**
-     * Invoke the compiler and transform its outputs.
-     * @param contractsToCompile list of contracts for which to generate doc objects
-     * @return doc objects for use with documentation generation tools.
-     */
-    public async generateAsync(contractsToCompile: string[]): Promise<DocAgnosticFormat> {
-        const shouldOverrideCatchAllContractsConfig = !_.isUndefined(contractsToCompile);
-        if (shouldOverrideCatchAllContractsConfig) {
-            this._compilerOptions.contracts = contractsToCompile;
-        }
 
-        const doc: DocAgnosticFormat = {};
-
-        const compiler = new Compiler(this._compilerOptions);
-        const compilerOutputs = await compiler.getCompilerOutputsAsync();
-        for (const compilerOutput of compilerOutputs) {
-            const contractFileNames = _.keys(compilerOutput.contracts);
-            for (const contractFileName of contractFileNames) {
-                const contractNameToOutput = compilerOutput.contracts[contractFileName];
-
-                const contractNames = _.keys(contractNameToOutput);
-                for (const contractName of contractNames) {
-                    const compiledContract = contractNameToOutput[contractName];
-                    if (_.isUndefined(compiledContract.abi)) {
-                        throw new Error('compiled contract did not contain ABI output.');
-                    }
-                    if (_.isUndefined(compiledContract.devdoc)) {
-                        throw new Error('compiled contract did not contain devdoc output.');
-                    }
-
-                    logUtils.log(
-                        `TODO: extract data from ${contractName}'s abi (eg name, which is "${
-                            (compiledContract.abi[0] as MethodAbi).name
-                        }", etc) and devdoc (eg title, which is "${
-                            compiledContract.devdoc.title
-                        }") outputs, and insert it into \`doc\``,
-                    );
-                }
-            }
+    return compilerOptions;
+}
+
+function _genDocSection(compiledContract: StandardContractOutput): DocSection {
+    const docSection: DocSection = {
+        comment: _.isUndefined(compiledContract.devdoc) ? '' : compiledContract.devdoc.title,
+        constructors: [],
+        methods: [],
+        properties: [],
+        types: [],
+        functions: [],
+        events: [],
+    };
+
+    for (const abiDefinition of compiledContract.abi) {
+        switch (abiDefinition.type) {
+            case 'constructor':
+                docSection.constructors.push(_genConstructorDoc(abiDefinition, compiledContract.devdoc));
+                break;
+            case 'event':
+                (docSection.events as Event[]).push(_genEventDoc(abiDefinition));
+                // note that we're not sending devdoc to _genEventDoc().
+                // that's because the type of the events array doesn't have any fields for documentation!
+                break;
+            case 'function':
+                docSection.methods.push(_genMethodDoc(abiDefinition, compiledContract.devdoc));
+                break;
+            default:
+                throw new Error(`unknown and unsupported AbiDefinition type '${abiDefinition.type}'`);
         }
+    }
+
+    return docSection;
+}
+
+function _genConstructorDoc(abiDefinition: ConstructorAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod {
+    const { parameters, methodSignature } = _genMethodParamsDoc(
+        '', // TODO: update depending on how constructors are keyed in devdoc
+        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';
+
+    return {
+        isConstructor: true,
+        name: '', // sad we have to specify this
+        callPath: '', // TODO: wtf is this?
+        parameters,
+        returnType: { name: '', typeDocType: TypeDocTypes.Intrinsic }, // sad we have to specify this
+        isConstant: false, // constructors are non-const by their nature, right?
+        isPayable: abiDefinition.payable,
+        comment,
+    };
+}
+
+function _genMethodDoc(
+    abiDefinition: MethodAbi | FallbackAbi,
+    devdocIfExists: DevdocOutput | undefined,
+): SolidityMethod {
+    const name = abiDefinition.type === 'fallback' ? '' : abiDefinition.name;
 
-        return doc;
+    const { parameters, methodSignature } =
+        abiDefinition.type === 'fallback'
+            ? { 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 returnType =
+        abiDefinition.type === 'fallback'
+            ? { name: '', typeDocType: TypeDocTypes.Intrinsic }
+            : _genMethodReturnTypeDoc(abiDefinition.outputs, methodSignature, devdocIfExists);
+
+    const isConstant = abiDefinition.type === 'fallback' ? true : abiDefinition.constant;
+    // TODO: determine whether fallback functions are always constant, as coded just above
+
+    return {
+        isConstructor: false,
+        name,
+        callPath: '', // TODO: wtf is this?
+        parameters,
+        returnType,
+        isConstant,
+        isPayable: abiDefinition.payable,
+        comment,
+    };
+}
+
+function _genEventDoc(abiDefinition: EventAbi): Event {
+    const eventDoc: Event = {
+        name: abiDefinition.name,
+        eventArgs: _genEventArgsDoc(abiDefinition.inputs, undefined),
+    };
+    return eventDoc;
+}
+
+function _genEventArgsDoc(args: DataItem[], devdocIfExists: DevdocOutput | undefined): EventArg[] {
+    const eventArgsDoc: EventArg[] = [];
+
+    for (const arg of args) {
+        const name = arg.name;
+
+        const type: Type = {
+            name: arg.type,
+            typeDocType: TypeDocTypes.Intrinsic,
+        };
+
+        const eventArgDoc: EventArg = {
+            isIndexed: false, // TODO: wtf is this?
+            name,
+            type,
+        };
+
+        eventArgsDoc.push(eventArgDoc);
+    }
+    return eventArgsDoc;
+}
+
+/**
+ * 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,
+    params: DataItem[],
+    devdocIfExists: DevdocOutput | undefined,
+): { parameters: Parameter[]; methodSignature: string } {
+    const parameters: Parameter[] = [];
+    for (const input of params) {
+        const parameter: Parameter = {
+            name: input.name,
+            comment: '', // TODO: get from devdoc. see comment below.
+            isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232
+            type: { name: input.type, typeDocType: TypeDocTypes.Intrinsic },
+        };
+        parameters.push(parameter);
+    }
+    // TODO: use methodSignature as the key to abiEntry.devdoc.methods, and
+    // from that object extract the "details" (comment) property
+    return { parameters, methodSignature: '' };
+}
+
+function _genMethodReturnTypeDoc(
+    outputs: DataItem[],
+    methodSignature: string,
+    devdocIfExists: DevdocOutput | undefined,
+): Type {
+    const methodReturnTypeDoc: Type = {
+        name: '',
+        typeDocType: TypeDocTypes.Intrinsic,
+        tupleElements: undefined,
+    };
+    if (outputs.length > 1) {
+        methodReturnTypeDoc.typeDocType = TypeDocTypes.Tuple;
+        methodReturnTypeDoc.tupleElements = [];
+        for (const output of outputs) {
+            methodReturnTypeDoc.tupleElements.push({ name: output.name, typeDocType: TypeDocTypes.Intrinsic });
+        }
+    } else if (outputs.length === 1) {
+        methodReturnTypeDoc.typeDocType = TypeDocTypes.Intrinsic;
+        methodReturnTypeDoc.name = outputs[0].name;
     }
+    return methodReturnTypeDoc;
 }
diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts
index 1df3e5b44..df6ad8e54 100644
--- a/packages/sol-doc/test/solidity_doc_generator_test.ts
+++ b/packages/sol-doc/test/solidity_doc_generator_test.ts
@@ -1,7 +1,11 @@
+import * as _ from 'lodash';
+
 import * as chai from 'chai';
 import 'mocha';
 
-import { SolidityDocGenerator } from '../src/solidity_doc_generator';
+import { DocSection } from '@0xproject/types';
+
+import { generateSolDocAsync } from '../src/solidity_doc_generator';
 
 import { chaiSetup } from './util/chai_setup';
 
@@ -9,11 +13,49 @@ chaiSetup.configure();
 const expect = chai.expect;
 
 describe('#SolidityDocGenerator', () => {
-    it('should generate', async () => {
-        const generator = new SolidityDocGenerator(`${__dirname}/../../test/fixtures/contracts`);
-
-        const doc = await generator.generateAsync(['TokenTransferProxy']);
+    it('should generate a doc object that matches the TokenTransferProxy fixture', async () => {
+        const doc = await generateSolDocAsync(['TokenTransferProxy'], `${__dirname}/../../test/fixtures/contracts`);
 
         expect(doc).to.not.be.undefined();
+
+        const tokenTransferProxyConstructorCount = 0;
+        const tokenTransferProxyMethodCount = 8;
+        const tokenTransferProxyEventCount = 3;
+        expect(doc.TokenTransferProxy.constructors.length).to.equal(tokenTransferProxyConstructorCount);
+        expect(doc.TokenTransferProxy.methods.length).to.equal(tokenTransferProxyMethodCount);
+        if (_.isUndefined(doc.TokenTransferProxy.events)) {
+            throw new Error('events should never be undefined');
+        }
+        expect(doc.TokenTransferProxy.events.length).to.equal(tokenTransferProxyEventCount);
+
+        const ownableConstructorCount = 1;
+        const ownableMethodCount = 2;
+        const ownableEventCount = 1;
+        expect(doc.Ownable.constructors.length).to.equal(ownableConstructorCount);
+        expect(doc.Ownable.methods.length).to.equal(ownableMethodCount);
+        if (_.isUndefined(doc.Ownable.events)) {
+            throw new Error('events should never be undefined');
+        }
+        expect(doc.Ownable.events.length).to.equal(ownableEventCount);
+
+        const erc20ConstructorCount = 0;
+        const erc20MethodCount = 6;
+        const erc20EventCount = 2;
+        expect(doc.ERC20.constructors.length).to.equal(erc20ConstructorCount);
+        expect(doc.ERC20.methods.length).to.equal(erc20MethodCount);
+        if (_.isUndefined(doc.ERC20.events)) {
+            throw new Error('events should never be undefined');
+        }
+        expect(doc.ERC20.events.length).to.equal(erc20EventCount);
+
+        const erc20BasicConstructorCount = 0;
+        const erc20BasicMethodCount = 3;
+        const erc20BasicEventCount = 1;
+        expect(doc.ERC20Basic.constructors.length).to.equal(erc20BasicConstructorCount);
+        expect(doc.ERC20Basic.methods.length).to.equal(erc20BasicMethodCount);
+        if (_.isUndefined(doc.ERC20Basic.events)) {
+            throw new Error('events should never be undefined');
+        }
+        expect(doc.ERC20Basic.events.length).to.equal(erc20BasicEventCount);
     });
 });