Merge pull request #1004 from feuGeneA/sol-doc

[ethereum-types, react-docs, sol-compiler, sol-doc, types, typescript-typings, website] Add new Solidity documentation generation utility

14 files changed, 919 insertions, 0 deletions

diff --git a/packages/sol-doc/CHANGELOG.json b/packages/sol-doc/CHANGELOG.json
new file mode 100644
index 000000000..c5bd78356
--- /dev/null
+++ b/packages/sol-doc/CHANGELOG.json
@@ -0,0 +1,12 @@
+[
+    {
+        "version": "1.0.0",
+        "changes": [
+            {
+                "note":
+                    "Utility to generate documentation for Solidity smart contracts, outputting a format compliant with @0xproject/types.DocAgnosticFormat",
+                "pr": 1004
+            }
+        ]
+    }
+]
diff --git a/packages/sol-doc/coverage/.gitkeep b/packages/sol-doc/coverage/.gitkeep
new file mode 100644
index 000000000..e69de29bb
--- /dev/null
+++ b/packages/sol-doc/coverage/.gitkeep
diff --git a/packages/sol-doc/package.json b/packages/sol-doc/package.json
new file mode 100644
index 000000000..618cb7ef7
--- /dev/null
+++ b/packages/sol-doc/package.json
@@ -0,0 +1,49 @@
+{
+    "name": "@0xproject/sol-doc",
+    "version": "1.0.0",
+    "description": "Solidity documentation generator",
+    "main": "lib/src/index.js",
+    "types": "lib/src/index.d.js",
+    "scripts": {
+        "build": "tsc",
+        "test": "mocha --require source-map-support/register --require make-promises-safe lib/test/**/*_test.js --timeout 6000 --exit",
+        "test:circleci": "yarn test:coverage",
+        "test:coverage": "nyc npm run test --all && yarn coverage:report:lcov",
+        "coverage:report:lcov": "nyc report --reporter=text-lcov > coverage/lcov.info",
+        "lint": "tslint --project . --format stylish",
+        "clean": "shx rm -rf lib",
+        "generate-v1-protocol-docs": "(cd ../contracts/src/1.0.0; node ../../../../node_modules/.bin/sol-doc --contracts-dir . --contracts Exchange/Exchange_v1.sol TokenRegistry/TokenRegistry.sol TokenTransferProxy/TokenTransferProxy_v1.sol) > v1.0.0.json",
+        "generate-v2-protocol-docs": "(cd ../contracts/src/2.0.0; node ../../../../node_modules/.bin/sol-doc --contracts-dir . --contracts $(cd protocol; ls -C1 */*.sol */interfaces/*.sol) ) > v2.0.0.json",
+        "deploy-v2-protocol-docs": "aws --profile 0xproject s3 cp --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json v2.0.0.json s3://staging-doc-jsons/contracts/",
+        "deploy-v1-protocol-docs": "aws --profile 0xproject s3 cp --grants read=uri=http://acs.amazonaws.com/groups/global/AllUsers --content-type application/json v1.0.0.json s3://staging-doc-jsons/contracts/"
+    },
+    "bin": {
+        "sol-doc": "bin/sol-doc.js"
+    },
+    "repository": "https://github.com/0xProject/0x-monorepo.git",
+    "author": "F. Eugene Aumson",
+    "license": "Apache-2.0",
+    "dependencies": {
+        "@0xproject/sol-compiler": "^1.1.5",
+        "@0xproject/types": "^1.1.1",
+        "@0xproject/utils": "^1.0.11",
+        "ethereum-types": "^1.0.4",
+        "lodash": "^4.17.10",
+        "yargs": "^12.0.2"
+    },
+    "devDependencies": {
+        "@0xproject/tslint-config": "^1.0.7",
+        "chai": "^4.1.2",
+        "chai-as-promised": "^7.1.0",
+        "chai-bignumber": "^2.0.2",
+        "dirty-chai": "^2.0.1",
+        "make-promises-safe": "^1.1.0",
+        "mocha": "^5.2.0",
+        "shx": "^0.2.2",
+        "source-map-support": "^0.5.0",
+        "tslint": "5.11.0"
+    },
+    "publishConfig": {
+        "access": "public"
+    }
+}
diff --git a/packages/sol-doc/src/cli.ts b/packages/sol-doc/src/cli.ts
new file mode 100644
index 000000000..eb0f00bf6
--- /dev/null
+++ b/packages/sol-doc/src/cli.ts
@@ -0,0 +1,28 @@
+import 'source-map-support/register';
+import * as yargs from 'yargs';
+
+import { logUtils } from '@0xproject/utils';
+
+import { generateSolDocAsync } from './solidity_doc_generator';
+
+const JSON_TAB_WIDTH = 4;
+
+(async () => {
+    const argv = yargs
+        .option('contracts-dir', {
+            type: 'string',
+            description: 'path of contracts directory to compile',
+        })
+        .option('contracts', {
+            type: 'string',
+            description: 'comma separated list of contracts to compile',
+        })
+        .demandOption('contracts-dir')
+        .array('contracts')
+        .help().argv;
+    const doc = await generateSolDocAsync(argv.contractsDir, argv.contracts);
+    process.stdout.write(JSON.stringify(doc, null, JSON_TAB_WIDTH));
+})().catch(err => {
+    logUtils.warn(err);
+    process.exit(1);
+});
diff --git a/packages/sol-doc/src/index.ts b/packages/sol-doc/src/index.ts
new file mode 100644
index 000000000..03f3c9de6
--- /dev/null
+++ b/packages/sol-doc/src/index.ts
@@ -0,0 +1 @@
+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
new file mode 100644
index 000000000..5ddf001a6
--- /dev/null
+++ b/packages/sol-doc/src/solidity_doc_generator.ts
@@ -0,0 +1,306 @@
+import * as path from 'path';
+
+import * as _ from 'lodash';
+
+import {
+    AbiDefinition,
+    ConstructorAbi,
+    DataItem,
+    DevdocOutput,
+    EventAbi,
+    EventParameter,
+    FallbackAbi,
+    MethodAbi,
+    StandardContractOutput,
+} from 'ethereum-types';
+
+import { Compiler, CompilerOptions } from '@0xproject/sol-compiler';
+import {
+    DocAgnosticFormat,
+    DocSection,
+    Event,
+    EventArg,
+    Parameter,
+    SolidityMethod,
+    Type,
+    TypeDocTypes,
+} from '@0xproject/types';
+
+/**
+ * Invoke the Solidity compiler and transform its ABI and devdoc outputs into a
+ * JSON format easily consumed by documentation rendering tools.
+ * @param contractsToDocument 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 async function generateSolDocAsync(
+    contractsDir: string,
+    contractsToDocument?: string[],
+): Promise<DocAgnosticFormat> {
+    const docWithDependencies: DocAgnosticFormat = {};
+    const compilerOptions = _makeCompilerOptions(contractsDir, contractsToDocument);
+    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');
+                }
+                docWithDependencies[contractName] = _genDocSection(compiledContract, contractName);
+            }
+        }
+    }
+
+    let doc: DocAgnosticFormat = {};
+    if (_.isUndefined(contractsToDocument) || contractsToDocument.length === 0) {
+        doc = docWithDependencies;
+    } else {
+        for (const contractToDocument of contractsToDocument) {
+            const contractBasename = path.basename(contractToDocument);
+            const contractName =
+                contractBasename.lastIndexOf('.sol') === -1
+                    ? contractBasename
+                    : contractBasename.substring(0, contractBasename.lastIndexOf('.sol'));
+            doc[contractName] = docWithDependencies[contractName];
+        }
+    }
+
+    return doc;
+}
+
+function _makeCompilerOptions(contractsDir: string, contractsToCompile?: string[]): CompilerOptions {
+    const compilerOptions: CompilerOptions = {
+        contractsDir,
+        contracts: '*',
+        compilerSettings: {
+            outputSelection: {
+                ['*']: {
+                    ['*']: ['abi', 'devdoc'],
+                },
+            },
+        },
+    };
+
+    const shouldOverrideCatchAllContractsConfig = !_.isUndefined(contractsToCompile) && contractsToCompile.length > 0;
+    if (shouldOverrideCatchAllContractsConfig) {
+        compilerOptions.contracts = contractsToCompile;
+    }
+
+    return compilerOptions;
+}
+
+function _genDocSection(compiledContract: StandardContractOutput, contractName: string): 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(contractName, 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':
+            case 'fallback':
+                docSection.methods.push(_genMethodDoc(abiDefinition, compiledContract.devdoc));
+                break;
+            default:
+                throw new Error(
+                    `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`,
+                );
+        }
+    }
+
+    return docSection;
+}
+
+function _genConstructorDoc(
+    contractName: string,
+    abiDefinition: ConstructorAbi,
+    devdocIfExists: DevdocOutput | undefined,
+): SolidityMethod {
+    const { parameters, methodSignature } = _genMethodParamsDoc('', abiDefinition.inputs, devdocIfExists);
+
+    const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
+
+    const constructorDoc: SolidityMethod = {
+        isConstructor: true,
+        name: contractName,
+        callPath: '',
+        parameters,
+        returnType: { name: contractName, typeDocType: TypeDocTypes.Reference }, // sad we have to specify this
+        isConstant: false,
+        isPayable: abiDefinition.payable,
+        comment,
+    };
+
+    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,
+): SolidityMethod {
+    const name = abiDefinition.type === 'fallback' ? '' : abiDefinition.name;
+
+    const { parameters, methodSignature } =
+        abiDefinition.type === 'fallback'
+            ? { parameters: [], methodSignature: `${name}()` }
+            : _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists);
+
+    const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
+
+    const returnType =
+        abiDefinition.type === 'fallback'
+            ? { name: '', typeDocType: TypeDocTypes.Intrinsic }
+            : _genMethodReturnTypeDoc(abiDefinition.outputs, methodSignature, devdocIfExists);
+
+    const returnComment =
+        _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature])
+            ? undefined
+            : devdocIfExists.methods[methodSignature].return;
+
+    const isConstant = abiDefinition.type === 'fallback' ? true : abiDefinition.constant;
+
+    const methodDoc: SolidityMethod = {
+        isConstructor: false,
+        name,
+        callPath: '',
+        parameters,
+        returnType,
+        returnComment,
+        isConstant,
+        isPayable: abiDefinition.payable,
+        comment,
+    };
+    return methodDoc;
+}
+
+function _genEventDoc(abiDefinition: EventAbi): Event {
+    const eventDoc: Event = {
+        name: abiDefinition.name,
+        eventArgs: _genEventArgsDoc(abiDefinition.inputs, undefined),
+    };
+    return eventDoc;
+}
+
+function _genEventArgsDoc(args: EventParameter[], 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: arg.indexed,
+            name,
+            type,
+        };
+
+        eventArgsDoc.push(eventArgDoc);
+    }
+    return eventArgsDoc;
+}
+
+/**
+ * Extract documentation for each method parameter from @param params.
+ */
+function _genMethodParamsDoc(
+    name: string,
+    abiParams: DataItem[],
+    devdocIfExists: DevdocOutput | undefined,
+): { parameters: Parameter[]; methodSignature: string } {
+    const parameters: Parameter[] = [];
+    for (const abiParam of abiParams) {
+        const parameter: Parameter = {
+            name: abiParam.name,
+            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);
+    }
+
+    const methodSignature = `${name}(${abiParams
+        .map(abiParam => {
+            return abiParam.type;
+        })
+        .join(',')})`;
+
+    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(
+    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.type, typeDocType: TypeDocTypes.Intrinsic });
+        }
+    } else if (outputs.length === 1) {
+        methodReturnTypeDoc.typeDocType = TypeDocTypes.Intrinsic;
+        methodReturnTypeDoc.name = outputs[0].type;
+    }
+    return methodReturnTypeDoc;
+}
diff --git a/packages/sol-doc/test/fixtures/contracts/MultipleReturnValues.sol b/packages/sol-doc/test/fixtures/contracts/MultipleReturnValues.sol
new file mode 100644
index 000000000..1e898622c
--- /dev/null
+++ b/packages/sol-doc/test/fixtures/contracts/MultipleReturnValues.sol
@@ -0,0 +1,7 @@
+pragma solidity ^0.4.24;
+
+contract MultipleReturnValues {
+    function methodWithMultipleReturnValues() public pure returns(int, int) {
+        return (0, 0);
+    }
+}
diff --git a/packages/sol-doc/test/fixtures/contracts/NatspecEverything.sol b/packages/sol-doc/test/fixtures/contracts/NatspecEverything.sol
new file mode 100644
index 000000000..c6ad3db81
--- /dev/null
+++ b/packages/sol-doc/test/fixtures/contracts/NatspecEverything.sol
@@ -0,0 +1,40 @@
+pragma solidity ^0.4.24;
+
+/// @title Contract Title
+/// @dev This is a very long documentation comment at the contract level.
+/// It actually spans multiple lines, too.
+contract NatspecEverything {
+    int d;
+
+    /// @dev Constructor @dev
+    /// @param p Constructor @param
+    constructor(int p) public { d = p; }
+
+    /// @notice publicMethod @notice
+    /// @dev publicMethod @dev
+    /// @param p publicMethod @param
+    /// @return publicMethod @return
+    function publicMethod(int p) public pure returns(int r) { return p; }
+
+    /// @dev Fallback @dev
+    function () public {}
+
+    /// @notice externalMethod @notice
+    /// @dev externalMethod @dev
+    /// @param p externalMethod @param
+    /// @return externalMethod @return
+    function externalMethod(int p) external pure returns(int r) { return p; }
+
+    /// @dev Here is a really long developer documentation comment, which spans
+    /// multiple lines, for the purposes of making sure that broken lines are
+    /// consolidated into one devdoc comment.
+    function methodWithLongDevdoc(int p) public pure returns(int) { return p; }
+
+    /// @dev AnEvent @dev
+    /// @param p on this event is an integer.
+    event AnEvent(int p);
+
+    /// @dev methodWithSolhintDirective @dev
+    // solhint-disable no-empty-blocks
+    function methodWithSolhintDirective() public pure {}
+}
diff --git a/packages/sol-doc/test/fixtures/contracts/TokenTransferProxy.sol b/packages/sol-doc/test/fixtures/contracts/TokenTransferProxy.sol
new file mode 100644
index 000000000..44570d459
--- /dev/null
+++ b/packages/sol-doc/test/fixtures/contracts/TokenTransferProxy.sol
@@ -0,0 +1,115 @@
+/*
+
+  Copyright 2018 ZeroEx Intl.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+*/
+
+pragma solidity ^0.4.14;
+
+import { Ownable } from "zeppelin-solidity/contracts/ownership/Ownable.sol";
+import { ERC20 as Token } from "zeppelin-solidity/contracts/token/ERC20/ERC20.sol";
+
+/// @title TokenTransferProxy - Transfers tokens on behalf of contracts that have been approved via decentralized governance.
+/// @author Amir Bandeali - <amir@0xProject.com>, Will Warren - <will@0xProject.com>
+contract TokenTransferProxy is Ownable {
+
+    /// @dev Only authorized addresses can invoke functions with this modifier.
+    modifier onlyAuthorized {
+        require(authorized[msg.sender]);
+        _;
+    }
+
+    modifier targetAuthorized(address target) {
+        require(authorized[target]);
+        _;
+    }
+
+    modifier targetNotAuthorized(address target) {
+        require(!authorized[target]);
+        _;
+    }
+
+    mapping (address => bool) public authorized;
+    address[] public authorities;
+
+    event LogAuthorizedAddressAdded(address indexed target, address indexed caller);
+    event LogAuthorizedAddressRemoved(address indexed target, address indexed caller);
+
+    /*
+     * Public functions
+     */
+
+    /// @dev Authorizes an address.
+    /// @param target Address to authorize.
+    function addAuthorizedAddress(address target)
+        public
+        onlyOwner
+        targetNotAuthorized(target)
+    {
+        authorized[target] = true;
+        authorities.push(target);
+        LogAuthorizedAddressAdded(target, msg.sender);
+    }
+
+    /// @dev Removes authorizion of an address.
+    /// @param target Address to remove authorization from.
+    function removeAuthorizedAddress(address target)
+        public
+        onlyOwner
+        targetAuthorized(target)
+    {
+        delete authorized[target];
+        for (uint i = 0; i < authorities.length; i++) {
+            if (authorities[i] == target) {
+                authorities[i] = authorities[authorities.length - 1];
+                authorities.length -= 1;
+                break;
+            }
+        }
+        LogAuthorizedAddressRemoved(target, msg.sender);
+    }
+
+    /// @dev Calls into ERC20 Token contract, invoking transferFrom.
+    /// @param token Address of token to transfer.
+    /// @param from Address to transfer token from.
+    /// @param to Address to transfer token to.
+    /// @param value Amount of token to transfer.
+    /// @return Success of transfer.
+    function transferFrom(
+        address token,
+        address from,
+        address to,
+        uint value)
+        public
+        onlyAuthorized
+        returns (bool)
+    {
+        return Token(token).transferFrom(from, to, value);
+    }
+
+    /*
+     * Public constant functions
+     */
+
+    /// @dev Gets all authorized addresses.
+    /// @return Array of authorized addresses.
+    function getAuthorizedAddresses()
+        public
+        constant
+        returns (address[])
+    {
+        return authorities;
+    }
+}
diff --git a/packages/sol-doc/test/fixtures/contracts/TokenTransferProxyNoDevdoc.sol b/packages/sol-doc/test/fixtures/contracts/TokenTransferProxyNoDevdoc.sol
new file mode 100644
index 000000000..cc45a79e9
--- /dev/null
+++ b/packages/sol-doc/test/fixtures/contracts/TokenTransferProxyNoDevdoc.sol
@@ -0,0 +1,100 @@
+/*
+
+  Copyright 2018 ZeroEx Intl.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+*/
+
+pragma solidity ^0.4.14;
+
+import { Ownable } from "zeppelin-solidity/contracts/ownership/Ownable.sol";
+import { ERC20 as Token } from "zeppelin-solidity/contracts/token/ERC20/ERC20.sol";
+
+contract TokenTransferProxyNoDevdoc is Ownable {
+
+    modifier onlyAuthorized {
+        require(authorized[msg.sender]);
+        _;
+    }
+
+    modifier targetAuthorized(address target) {
+        require(authorized[target]);
+        _;
+    }
+
+    modifier targetNotAuthorized(address target) {
+        require(!authorized[target]);
+        _;
+    }
+
+    mapping (address => bool) public authorized;
+    address[] public authorities;
+
+    event LogAuthorizedAddressAdded(address indexed target, address indexed caller);
+    event LogAuthorizedAddressRemoved(address indexed target, address indexed caller);
+
+    /*
+     * Public functions
+     */
+
+    function addAuthorizedAddress(address target)
+        public
+        onlyOwner
+        targetNotAuthorized(target)
+    {
+        authorized[target] = true;
+        authorities.push(target);
+        LogAuthorizedAddressAdded(target, msg.sender);
+    }
+
+    function removeAuthorizedAddress(address target)
+        public
+        onlyOwner
+        targetAuthorized(target)
+    {
+        delete authorized[target];
+        for (uint i = 0; i < authorities.length; i++) {
+            if (authorities[i] == target) {
+                authorities[i] = authorities[authorities.length - 1];
+                authorities.length -= 1;
+                break;
+            }
+        }
+        LogAuthorizedAddressRemoved(target, msg.sender);
+    }
+
+    function transferFrom(
+        address token,
+        address from,
+        address to,
+        uint value)
+        public
+        onlyAuthorized
+        returns (bool)
+    {
+        return Token(token).transferFrom(from, to, value);
+    }
+
+    /*
+     * Public constant functions
+     */
+
+    function getAuthorizedAddresses()
+        public
+        constant
+        returns (address[])
+    {
+        return authorities;
+    }
+}
diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts
new file mode 100644
index 000000000..c780d3d31
--- /dev/null
+++ b/packages/sol-doc/test/solidity_doc_generator_test.ts
@@ -0,0 +1,237 @@
+import * as _ from 'lodash';
+
+import * as chai from 'chai';
+import 'mocha';
+
+import { DocAgnosticFormat, Event, SolidityMethod } from '@0xproject/types';
+
+import { generateSolDocAsync } from '../src/solidity_doc_generator';
+
+import { chaiSetup } from './util/chai_setup';
+
+chaiSetup.configure();
+const expect = chai.expect;
+
+describe('#SolidityDocGenerator', () => {
+    it('should generate a doc object that matches the devdoc-free TokenTransferProxy fixture', async () => {
+        const doc = await generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [
+            'TokenTransferProxyNoDevdoc',
+        ]);
+        expect(doc).to.not.be.undefined();
+
+        verifyTokenTransferProxyABIIsDocumented(doc, 'TokenTransferProxyNoDevdoc');
+    });
+    const docPromises: Array<Promise<DocAgnosticFormat>> = [
+        generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`),
+        generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, []),
+    ];
+    docPromises.forEach(docPromise => {
+        it('should generate a doc object that matches the TokenTransferProxy fixture with its dependencies', async () => {
+            const doc = await docPromise;
+            expect(doc).to.not.be.undefined();
+
+            verifyTokenTransferProxyAndDepsABIsAreDocumented(doc, 'TokenTransferProxy');
+
+            let addAuthorizedAddressMethod: SolidityMethod | undefined;
+            for (const method of doc.TokenTransferProxy.methods) {
+                if (method.name === 'addAuthorizedAddress') {
+                    addAuthorizedAddressMethod = method;
+                }
+            }
+            const tokenTransferProxyAddAuthorizedAddressComment = 'Authorizes an address.';
+            expect((addAuthorizedAddressMethod as SolidityMethod).comment).to.equal(
+                tokenTransferProxyAddAuthorizedAddressComment,
+            );
+
+            const expectedParamComment = 'Address to authorize.';
+            expect((addAuthorizedAddressMethod as SolidityMethod).parameters[0].comment).to.equal(expectedParamComment);
+        });
+    });
+    it('should generate a doc object that matches the TokenTransferProxy fixture', async () => {
+        const doc: DocAgnosticFormat = await generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [
+            'TokenTransferProxy',
+        ]);
+        verifyTokenTransferProxyABIIsDocumented(doc, 'TokenTransferProxy');
+    });
+    describe('when processing all the permutations of devdoc stuff that we use in our contracts', () => {
+        let doc: DocAgnosticFormat;
+        before(async () => {
+            doc = await generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, ['NatspecEverything']);
+            expect(doc).to.not.be.undefined();
+            expect(doc.NatspecEverything).to.not.be.undefined();
+        });
+        it('should emit the contract @title as its comment', () => {
+            expect(doc.NatspecEverything.comment).to.equal('Contract Title');
+        });
+        describe('should emit public method documentation for', () => {
+            let methodDoc: SolidityMethod;
+            before(() => {
+                // tslint:disable-next-line:no-unnecessary-type-assertion
+                methodDoc = doc.NatspecEverything.methods.find(method => {
+                    return method.name === 'publicMethod';
+                }) as SolidityMethod;
+                if (_.isUndefined(methodDoc)) {
+                    throw new Error('publicMethod not found');
+                }
+            });
+            it('method name', () => {
+                expect(methodDoc.name).to.equal('publicMethod');
+            });
+            it('method comment', () => {
+                expect(methodDoc.comment).to.equal('publicMethod @dev');
+            });
+            it('parameter name', () => {
+                expect(methodDoc.parameters[0].name).to.equal('p');
+            });
+            it('parameter comment', () => {
+                expect(methodDoc.parameters[0].comment).to.equal('publicMethod @param');
+            });
+            it('return type', () => {
+                expect(methodDoc.returnType.name).to.equal('int256');
+            });
+            it('return comment', () => {
+                expect(methodDoc.returnComment).to.equal('publicMethod @return');
+            });
+        });
+        describe('should emit external method documentation for', () => {
+            let methodDoc: SolidityMethod;
+            before(() => {
+                // tslint:disable-next-line:no-unnecessary-type-assertion
+                methodDoc = doc.NatspecEverything.methods.find(method => {
+                    return method.name === 'externalMethod';
+                }) as SolidityMethod;
+                if (_.isUndefined(methodDoc)) {
+                    throw new Error('externalMethod not found');
+                }
+            });
+            it('method name', () => {
+                expect(methodDoc.name).to.equal('externalMethod');
+            });
+            it('method comment', () => {
+                expect(methodDoc.comment).to.equal('externalMethod @dev');
+            });
+            it('parameter name', () => {
+                expect(methodDoc.parameters[0].name).to.equal('p');
+            });
+            it('parameter comment', () => {
+                expect(methodDoc.parameters[0].comment).to.equal('externalMethod @param');
+            });
+            it('return type', () => {
+                expect(methodDoc.returnType.name).to.equal('int256');
+            });
+            it('return comment', () => {
+                expect(methodDoc.returnComment).to.equal('externalMethod @return');
+            });
+        });
+        it('should not truncate a multi-line devdoc comment', () => {
+            // tslint:disable-next-line:no-unnecessary-type-assertion
+            const methodDoc: SolidityMethod = doc.NatspecEverything.methods.find(method => {
+                return method.name === 'methodWithLongDevdoc';
+            }) as SolidityMethod;
+            if (_.isUndefined(methodDoc)) {
+                throw new Error('methodWithLongDevdoc not found');
+            }
+            expect(methodDoc.comment).to.equal(
+                'Here is a really long developer documentation comment, which spans multiple lines, for the purposes of making sure that broken lines are consolidated into one devdoc comment.',
+            );
+        });
+        describe('should emit event documentation for', () => {
+            let eventDoc: Event;
+            before(() => {
+                eventDoc = (doc.NatspecEverything.events as Event[])[0];
+            });
+            it('event name', () => {
+                expect(eventDoc.name).to.equal('AnEvent');
+            });
+            it('parameter name', () => {
+                expect(eventDoc.eventArgs[0].name).to.equal('p');
+            });
+        });
+        it('should not let solhint directives obscure natspec content', () => {
+            // tslint:disable-next-line:no-unnecessary-type-assertion
+            const methodDoc: SolidityMethod = doc.NatspecEverything.methods.find(method => {
+                return method.name === 'methodWithSolhintDirective';
+            }) as SolidityMethod;
+            if (_.isUndefined(methodDoc)) {
+                throw new Error('methodWithSolhintDirective not found');
+            }
+            expect(methodDoc.comment).to.equal('methodWithSolhintDirective @dev');
+        });
+    });
+    it('should document a method that returns multiple values', async () => {
+        const doc = await generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, ['MultipleReturnValues']);
+        expect(doc.MultipleReturnValues).to.not.be.undefined();
+        expect(doc.MultipleReturnValues.methods).to.not.be.undefined();
+        let methodWithMultipleReturnValues: SolidityMethod | undefined;
+        for (const method of doc.MultipleReturnValues.methods) {
+            if (method.name === 'methodWithMultipleReturnValues') {
+                methodWithMultipleReturnValues = method;
+            }
+        }
+        if (_.isUndefined(methodWithMultipleReturnValues)) {
+            throw new Error('method should not be undefined');
+        }
+        const returnType = methodWithMultipleReturnValues.returnType;
+        expect(returnType.typeDocType).to.equal('tuple');
+        if (_.isUndefined(returnType.tupleElements)) {
+            throw new Error('returnType.tupleElements should not be undefined');
+        }
+        expect(returnType.tupleElements.length).to.equal(2);
+    });
+});
+
+function verifyTokenTransferProxyABIIsDocumented(doc: DocAgnosticFormat, contractName: string): void {
+    expect(doc[contractName]).to.not.be.undefined();
+    expect(doc[contractName].constructors).to.not.be.undefined();
+    const tokenTransferProxyConstructorCount = 0;
+    const tokenTransferProxyMethodCount = 8;
+    const tokenTransferProxyEventCount = 3;
+    expect(doc[contractName].constructors.length).to.equal(tokenTransferProxyConstructorCount);
+    expect(doc[contractName].methods.length).to.equal(tokenTransferProxyMethodCount);
+    const events = doc[contractName].events;
+    if (_.isUndefined(events)) {
+        throw new Error('events should never be undefined');
+    }
+    expect(events.length).to.equal(tokenTransferProxyEventCount);
+}
+
+function verifyTokenTransferProxyAndDepsABIsAreDocumented(doc: DocAgnosticFormat, contractName: string): void {
+    verifyTokenTransferProxyABIIsDocumented(doc, contractName);
+
+    expect(doc.ERC20).to.not.be.undefined();
+    expect(doc.ERC20.constructors).to.not.be.undefined();
+    expect(doc.ERC20.methods).to.not.be.undefined();
+    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);
+
+    expect(doc.ERC20Basic).to.not.be.undefined();
+    expect(doc.ERC20Basic.constructors).to.not.be.undefined();
+    expect(doc.ERC20Basic.methods).to.not.be.undefined();
+    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);
+
+    let addAuthorizedAddressMethod: SolidityMethod | undefined;
+    for (const method of doc[contractName].methods) {
+        if (method.name === 'addAuthorizedAddress') {
+            addAuthorizedAddressMethod = method;
+        }
+    }
+    expect(
+        addAuthorizedAddressMethod,
+        `method addAuthorizedAddress not found in ${JSON.stringify(doc[contractName].methods)}`,
+    ).to.not.be.undefined();
+}
diff --git a/packages/sol-doc/test/util/chai_setup.ts b/packages/sol-doc/test/util/chai_setup.ts
new file mode 100644
index 000000000..1a8733093
--- /dev/null
+++ b/packages/sol-doc/test/util/chai_setup.ts
@@ -0,0 +1,13 @@
+import * as chai from 'chai';
+import chaiAsPromised = require('chai-as-promised');
+import ChaiBigNumber = require('chai-bignumber');
+import * as dirtyChai from 'dirty-chai';
+
+export const chaiSetup = {
+    configure(): void {
+        chai.config.includeStack = true;
+        chai.use(ChaiBigNumber());
+        chai.use(dirtyChai);
+        chai.use(chaiAsPromised);
+    },
+};
diff --git a/packages/sol-doc/tsconfig.json b/packages/sol-doc/tsconfig.json
new file mode 100644
index 000000000..2ee711adc
--- /dev/null
+++ b/packages/sol-doc/tsconfig.json
@@ -0,0 +1,8 @@
+{
+    "extends": "../../tsconfig",
+    "compilerOptions": {
+        "outDir": "lib",
+        "rootDir": "."
+    },
+    "include": ["./src/**/*", "./test/**/*"]
+}
diff --git a/packages/sol-doc/tslint.json b/packages/sol-doc/tslint.json
new file mode 100644
index 000000000..ffaefe83a
--- /dev/null
+++ b/packages/sol-doc/tslint.json
@@ -0,0 +1,3 @@
+{
+    "extends": ["@0xproject/tslint-config"]
+}