From a1959df911741d0424a952fa4a63c5dcc1135524 Mon Sep 17 00:00:00 2001 From: "F. Eugene Aumson" Date: Fri, 24 Aug 2018 09:18:33 -0400 Subject: add devdoc support to solc typings, and use it --- packages/ethereum-types/src/index.ts | 62 ++++++++++++++++++++++ packages/monorepo-scripts/src/doc_gen_configs.ts | 2 + packages/sol-compiler/src/compiler.ts | 11 ++-- packages/sol-compiler/src/index.ts | 21 +++++++- packages/sol-doc/src/solidity_doc_generator.ts | 14 +++-- packages/typescript-typings/types/solc/index.d.ts | 63 +++-------------------- 6 files changed, 104 insertions(+), 69 deletions(-) (limited to 'packages') 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 { + public async getCompilerOutputsAsync(): Promise { 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 { + private async _compileContractsAsync(contractNames: string[], shouldPersist: boolean): Promise { // 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; } -- cgit v1.2.3