diff options
Diffstat (limited to 'packages/sol-doc/src/solidity_doc_generator.ts')
| -rw-r--r-- | packages/sol-doc/src/solidity_doc_generator.ts | 306 |
1 files changed, 0 insertions, 306 deletions
diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts deleted file mode 100644 index 5ddf001a6..000000000 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ /dev/null @@ -1,306 +0,0 @@ -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; -} |