add devdoc support to solc typings, and use it

6 files changed, 104 insertions, 69 deletions

diff --git a/packages/ethereum-types/src/index.ts b/packages/ethereum-types/src/index.ts
index 3b6fdc77b..993306a43 100644
--- a/packages/ethereum-types/src/index.ts
+++ b/packages/ethereum-types/src/index.ts
@@ -324,9 +324,56 @@ export interface ContractNetworkData {
     constructorArgs: string;
 }
 
+export type ParamDescription = string;
+
 export interface StandardContractOutput {
     abi: ContractAbi;
     evm: EvmOutput;
+    devdoc?: DevdocOutput;
+}
+
+export interface StandardOutput {
+    errors: SolcError[];
+    sources: {
+        [fileName: string]: {
+            id: number;
+            ast?: object;
+            legacyAST?: object;
+        };
+    };
+    contracts: {
+        [fileName: string]: {
+            [contractName: string]: StandardContractOutput;
+        };
+    };
+}
+
+export type ErrorType =
+    | 'JSONError'
+    | 'IOError'
+    | 'ParserError'
+    | 'DocstringParsingError'
+    | 'SyntaxError'
+    | 'DeclarationError'
+    | 'TypeError'
+    | 'UnimplementedFeatureError'
+    | 'InternalCompilerError'
+    | 'Exception'
+    | 'CompilerError'
+    | 'FatalError'
+    | 'Warning';
+export type ErrorSeverity = 'error' | 'warning';
+export interface SolcError {
+    sourceLocation?: {
+        file: string;
+        start: number;
+        end: number;
+    };
+    type: ErrorType;
+    component: 'general' | 'ewasm';
+    severity: ErrorSeverity;
+    message: string;
+    formattedMessage?: string;
 }
 
 export interface EvmOutput {
@@ -339,6 +386,20 @@ export interface EvmBytecodeOutput {
     sourceMap: string;
 }
 
+export interface DevdocOutput {
+    title: string;
+    author: string;
+    methods: {
+        [signature: string]: {
+            details: string;
+            params: {
+                [name: string]: ParamDescription;
+            };
+            return?: string;
+        };
+    };
+}
+
 export interface ContractVersionData {
     compiler: CompilerOpts;
     sources: {
@@ -415,6 +476,7 @@ export interface Source {
     id: number;
 }
 
+// TODO: move the following into the sol-compiler package.
 /**
  * Options you can specify (as flags or in a compiler.json file) when invoking sol-compiler
  * contractsDir: Directory containing your project's Solidity contracts. Can contain nested directories.
diff --git a/packages/monorepo-scripts/src/doc_gen_configs.ts b/packages/monorepo-scripts/src/doc_gen_configs.ts
index 6d7560943..9c0e19cb3 100644
--- a/packages/monorepo-scripts/src/doc_gen_configs.ts
+++ b/packages/monorepo-scripts/src/doc_gen_configs.ts
@@ -13,6 +13,8 @@ export const docGenConfigs: DocGenConfigs = {
         'solc.StandardContractOutput':
             'https://solidity.readthedocs.io/en/v0.4.24/using-the-compiler.html#output-description',
         'solc.CompilerSettings': 'https://solidity.readthedocs.io/en/v0.4.24/using-the-compiler.html#input-description',
+        StandardOutput: 'https://solidity.readthedocs.io/en/v0.4.24/using-the-compiler.html#input-description',
+        'solc.StandardOutput': 'https://solidity.readthedocs.io/en/v0.4.24/using-the-compiler.html#input-description',
         Schema:
             'https://github.com/tdegrunt/jsonschema/blob/5c2edd4baba149964aec0f23c87ad12c25a50dfb/lib/index.d.ts#L49',
         Uint8Array: 'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array',
diff --git a/packages/sol-compiler/src/compiler.ts b/packages/sol-compiler/src/compiler.ts
index 91b17c4f2..b5255b361 100644
--- a/packages/sol-compiler/src/compiler.ts
+++ b/packages/sol-compiler/src/compiler.ts
@@ -10,7 +10,7 @@ import {
 } from '@0xproject/sol-resolver';
 import { fetchAsync, logUtils } from '@0xproject/utils';
 import chalk from 'chalk';
-import { CompilerOptions, ContractArtifact, ContractVersionData } from 'ethereum-types';
+import { CompilerOptions, ContractArtifact, ContractVersionData, StandardOutput } from 'ethereum-types';
 import * as ethUtil from 'ethereumjs-util';
 import * as fs from 'fs';
 import * as _ from 'lodash';
@@ -169,7 +169,7 @@ export class Compiler {
      * each element contains the output for all of the modules compiled with
      * that version.
      */
-    public async getCompilerOutputsAsync(): Promise<solc.StandardOutput[]> {
+    public async getCompilerOutputsAsync(): Promise<StandardOutput[]> {
         return this._compileContractsAsync(this._getContractNamesToCompile(), false);
     }
     private _getContractNamesToCompile(): string[] {
@@ -187,10 +187,7 @@ export class Compiler {
      * @param fileName Name of contract with '.sol' extension.
      * @return an array of compiler outputs, where each element corresponds to a different version of solc-js.
      */
-    private async _compileContractsAsync(
-        contractNames: string[],
-        shouldPersist: boolean,
-    ): Promise<solc.StandardOutput[]> {
+    private async _compileContractsAsync(contractNames: string[], shouldPersist: boolean): Promise<StandardOutput[]> {
         // batch input contracts together based on the version of the compiler that they require.
         const versionToInputs: VersionToInputs = {};
 
@@ -231,7 +228,7 @@ export class Compiler {
             versionToInputs[solcVersion].contractsToCompile.push(contractSource.path);
         }
 
-        const compilerOutputs: solc.StandardOutput[] = [];
+        const compilerOutputs: StandardOutput[] = [];
 
         const solcVersions = _.keys(versionToInputs);
         for (const solcVersion of solcVersions) {
diff --git a/packages/sol-compiler/src/index.ts b/packages/sol-compiler/src/index.ts
index 1ad07a9ff..829e515ff 100644
--- a/packages/sol-compiler/src/index.ts
+++ b/packages/sol-compiler/src/index.ts
@@ -1,9 +1,28 @@
 export { Compiler } from './compiler';
 export {
+    AbiDefinition,
     CompilerOptions,
     CompilerSettings,
+    DataItem,
+    DevdocOutput,
+    ErrorSeverity,
+    ErrorType,
+    EventAbi,
+    EventParameter,
+    EvmBytecodeOutput,
+    EvmOutput,
+    FallbackAbi,
+    FunctionAbi,
+    MethodAbi,
+    ConstructorAbi,
+    ConstructorStateMutability,
+    ContractAbi,
     OutputField,
     CompilerSettingsMetadata,
     OptimizerSettings,
+    ParamDescription,
+    SolcError,
+    StandardContractOutput,
+    StandardOutput,
+    StateMutability,
 } from 'ethereum-types';
-export { StandardOutput } from 'solc';
diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts
index c57a4779c..fa3c40dcc 100644
--- a/packages/sol-doc/src/solidity_doc_generator.ts
+++ b/packages/sol-doc/src/solidity_doc_generator.ts
@@ -43,13 +43,19 @@ export class SolidityDocGenerator {
                 const contracts = _.keys(compiledSolidityModule);
                 for (const contract of contracts) {
                     const compiledContract = compiledSolidityModule[contract];
+                    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.');
+                    }
 
-                    // TODO: modify typescript-typings/types/solc/index.d.ts... it doesn't currently support devdoc!
-                    // tslint:disable-next-line:no-unnecessary-type-assertion tsc says abi[0] has no property `name` and won't compile without the `as`, but tslint says the `as` is unnecssary.
                     logUtils.log(
-                        `TODO: extract data from ${contract}'s abi (eg ${
+                        `TODO: extract data from ${contract}'s abi (eg name, which is "${
                             (compiledContract.abi[0] as MethodAbi).name
-                        }, etc) and devdoc outputs, and insert it into \`doc\``,
+                        }", etc) and devdoc (eg title, which is "${
+                            compiledContract.devdoc.title
+                        }") outputs, and insert it into \`doc\``,
                     );
                 }
             }
diff --git a/packages/typescript-typings/types/solc/index.d.ts b/packages/typescript-typings/types/solc/index.d.ts
index 571bae101..2cfd4a030 100644
--- a/packages/typescript-typings/types/solc/index.d.ts
+++ b/packages/typescript-typings/types/solc/index.d.ts
@@ -1,4 +1,5 @@
 declare module 'solc' {
+    import { SolcError } from 'ethereum-types';
     export interface ContractCompilationResult {
         srcmap: string;
         srcmapRuntime: string;
@@ -87,62 +88,7 @@ declare module 'solc' {
         };
         settings: CompilerSettings;
     }
-    export type ErrorType =
-        | 'JSONError'
-        | 'IOError'
-        | 'ParserError'
-        | 'DocstringParsingError'
-        | 'SyntaxError'
-        | 'DeclarationError'
-        | 'TypeError'
-        | 'UnimplementedFeatureError'
-        | 'InternalCompilerError'
-        | 'Exception'
-        | 'CompilerError'
-        | 'FatalError'
-        | 'Warning';
-    export type ErrorSeverity = 'error' | 'warning';
-    export interface Error {
-        sourceLocation?: {
-            file: string;
-            start: number;
-            end: number;
-        };
-        type: ErrorType;
-        component: 'general' | 'ewasm';
-        severity: ErrorSeverity;
-        message: string;
-        formattedMessage?: string;
-    }
-    import { ContractAbi } from 'ethereum-types';
-    export interface StandardContractOutput {
-        abi: ContractAbi;
-        evm: {
-            bytecode: {
-                object: string;
-                sourceMap: string;
-            };
-            deployedBytecode: {
-                object: string;
-                sourceMap: string;
-            };
-        };
-    }
-    export interface StandardOutput {
-        errors: Error[];
-        sources: {
-            [fileName: string]: {
-                id: number;
-                ast?: object;
-                legacyAST?: object;
-            };
-        };
-        contracts: {
-            [fileName: string]: {
-                [contractName: string]: StandardContractOutput;
-            };
-        };
-    }
+    export { ErrorType, ErrorSeverity, SolcError, StandardContractOutput, StandardOutput } from 'ethereum-types';
     export interface SolcInstance {
         compile(
             sources: InputSources,
@@ -151,6 +97,9 @@ declare module 'solc' {
         ): CompilationResult;
         compileStandardWrapper(input: string, findImports: (importPath: string) => ImportContents): string;
     }
-    export function loadRemoteVersion(versionName: string, cb: (err: Error | null, res?: SolcInstance) => void): void;
+    export function loadRemoteVersion(
+        versionName: string,
+        cb: (err: SolcError | null, res?: SolcInstance) => void,
+    ): void;
     export function setupMethods(solcBin: any): SolcInstance;
 }