From c55a41917851e66e3803883cf10b1e336e2dfc21 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 10:57:42 +0100 Subject: Split _genMethodDoc into it and _genFallbackDoc for clarity. Add isFallback boolean --- packages/sol-doc/src/solidity_doc_generator.ts | 54 +++++++++++++++----------- packages/types/src/index.ts | 1 + 2 files changed, 33 insertions(+), 22 deletions(-) diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index 5ddf001a6..d2fb5b083 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -117,8 +117,10 @@ function _genDocSection(compiledContract: StandardContractOutput, contractName: // that's because the type of the events array doesn't have any fields for documentation! break; case 'function': + docSection.methods.push(_genMethodDoc(abiDefinition as MethodAbi, compiledContract.devdoc)); + break; case 'fallback': - docSection.methods.push(_genMethodDoc(abiDefinition, compiledContract.devdoc)); + docSection.methods.push(_genFallbackDoc(abiDefinition as FallbackAbi, compiledContract.devdoc)); break; default: throw new Error( @@ -173,39 +175,47 @@ function _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); - +function _genFallbackDoc(abiDefinition: FallbackAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { + const methodSignature = `${name}()`; 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: { name: 'void', typeDocType: TypeDocTypes.Intrinsic }, + returnComment, + isConstant: true, + isPayable: abiDefinition.payable, + isFallback: true, + comment, + }; + return methodDoc; +} + +function _genMethodDoc(abiDefinition: MethodAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { + const { parameters, methodSignature } = _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists); + const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); + const returnType = _genMethodReturnTypeDoc(abiDefinition.outputs, methodSignature, devdocIfExists); + const returnComment = + _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature]) + ? undefined + : devdocIfExists.methods[methodSignature].return; const methodDoc: SolidityMethod = { isConstructor: false, - name, + name: abiDefinition.name, callPath: '', parameters, returnType, returnComment, - isConstant, + isConstant: abiDefinition.constant, isPayable: abiDefinition.payable, comment, }; @@ -254,7 +264,7 @@ function _genMethodParamsDoc( for (const abiParam of abiParams) { const parameter: Parameter = { name: abiParam.name, - comment: '', + comment: '', isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232 type: { name: abiParam.type, typeDocType: TypeDocTypes.Intrinsic }, }; @@ -288,7 +298,7 @@ function _genMethodReturnTypeDoc( devdocIfExists: DevdocOutput | undefined, ): Type { const methodReturnTypeDoc: Type = { - name: '', + name: 'void', typeDocType: TypeDocTypes.Intrinsic, tupleElements: undefined, }; diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts index 5ef8b54a4..3ae0536d5 100644 --- a/packages/types/src/index.ts +++ b/packages/types/src/index.ts @@ -519,6 +519,7 @@ export interface TypescriptFunction extends BaseFunction { export interface SolidityMethod extends BaseMethod { isConstant?: boolean; isPayable?: boolean; + isFallback?: boolean; } export interface Source { -- cgit v1.2.3 From 5cc11912a70f33112983736197d20de941f18137 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 18:39:27 +0100 Subject: Pull in only contracts we want rendered on the doc page --- packages/sol-doc/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/sol-doc/package.json b/packages/sol-doc/package.json index 618cb7ef7..873540215 100644 --- a/packages/sol-doc/package.json +++ b/packages/sol-doc/package.json @@ -13,7 +13,7 @@ "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", + "generate-v2-protocol-docs": "(cd ../contracts/src/2.0.0; node ../../../../node_modules/.bin/sol-doc --contracts-dir . --contracts Exchange/Exchange.sol AssetProxy/ERC20Proxy.sol AssetProxy/ERC721Proxy.sol OrderValidator/OrderValidator.sol Forwarder/Forwarder.sol AssetProxyOwner/AssetProxyOwner.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/" }, -- cgit v1.2.3 From c0498944c38e827dc69f369dd1427df43b23c9a9 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 18:40:38 +0100 Subject: Add more robust key --- packages/react-docs/src/components/documentation.tsx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 3cd14923c..55aa1587e 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -10,6 +10,7 @@ import { utils as sharedUtils, } from '@0xproject/react-shared'; import { + CustomType, DocAgnosticFormat, Event, ExternalExportToLink, @@ -218,11 +219,11 @@ export class Documentation extends React.Component { + const typeDefs = _.map(sortedTypes, (customType: CustomType, i: number) => { return ( Date: Thu, 27 Sep 2018 18:51:30 +0100 Subject: Add typeSectionName to docsInfo so we don't use hard-coded "Types" --- packages/react-docs/src/components/documentation.tsx | 2 +- packages/react-docs/src/docs_info.ts | 8 +++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index 55aa1587e..f1cb32b68 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -266,7 +266,7 @@ export class Documentation extends React.Component
- +
{this._renderNetworkBadgesIfExists(sectionName)}
diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index 6355a2f88..bf6aa07a7 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -18,6 +18,7 @@ export class DocsInfo { public packageName: string; public packageUrl: string; public menu: DocsMenu; + public typeSectionName: string; public sections: SectionsMap; public sectionNameToMarkdownByVersion: SectionNameToMarkdownByVersion; public contractsByVersionByNetworkId?: ContractsByVersionByNetworkId; @@ -28,6 +29,7 @@ export class DocsInfo { this.displayName = config.displayName; this.packageName = config.packageName; this.packageUrl = config.packageUrl; + this.typeSectionName = config.type === SupportedDocJson.SolDoc ? 'structs' : 'types'; this.sections = config.markdownSections; this.sectionNameToMarkdownByVersion = config.sectionNameToMarkdownByVersion; this.contractsByVersionByNetworkId = config.contractsByVersionByNetworkId; @@ -53,7 +55,7 @@ export class DocsInfo { _.isEmpty(docSection.properties) && _.isEmpty(docSection.events); - if (!_.isUndefined(this.sections.types) && sectionName === this.sections.types) { + if (sectionName === this.typeSectionName) { const sortedTypesNames = _.sortBy(docSection.types, 'name'); const typeNames = _.map(sortedTypesNames, t => t.name); menuSubsectionsBySection[sectionName] = typeNames; @@ -86,8 +88,8 @@ export class DocsInfo { return {}; } - const typeDocSection = docAgnosticFormat[this.sections.types]; - const typeDefinitionByName = _.keyBy(typeDocSection.types, 'name') as any; + const section = docAgnosticFormat[this.sections.types]; + const typeDefinitionByName = _.keyBy(section.types, 'name') as any; return typeDefinitionByName; } } -- cgit v1.2.3 From ceff5c9c2b0af9506ac281febf7fd487c05650d7 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 18:52:14 +0100 Subject: Rename for clarity --- packages/website/ts/pages/documentation/doc_page.tsx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packages/website/ts/pages/documentation/doc_page.tsx b/packages/website/ts/pages/documentation/doc_page.tsx index 6f029b6a2..87a806b2b 100644 --- a/packages/website/ts/pages/documentation/doc_page.tsx +++ b/packages/website/ts/pages/documentation/doc_page.tsx @@ -146,9 +146,9 @@ export class DocPage extends React.Component { docAgnosticFormat = versionDocObj as DocAgnosticFormat; // HACK: need to modify docsInfo like convertToDocAgnosticFormat() would do this.props.docsInfo.menu.Contracts = []; - _.each(docAgnosticFormat, (docObj, contractName) => { - this.props.docsInfo.sections[contractName] = contractName; - this.props.docsInfo.menu.Contracts.push(contractName); + _.each(docAgnosticFormat, (_docObj, sectionName) => { + this.props.docsInfo.sections[sectionName] = sectionName; + this.props.docsInfo.menu.Contracts.push(sectionName); }); } -- cgit v1.2.3 From e7b1374f23bfe098457b94ae51fac920aab6167b Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 18:52:37 +0100 Subject: Fix dropdown menu item so it says "0x smart contracts" not "smart contract" --- packages/website/ts/components/top_bar/top_bar.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/website/ts/components/top_bar/top_bar.tsx b/packages/website/ts/components/top_bar/top_bar.tsx index bb61e4fb9..7cf3c6ecb 100644 --- a/packages/website/ts/components/top_bar/top_bar.tsx +++ b/packages/website/ts/components/top_bar/top_bar.tsx @@ -136,7 +136,7 @@ export class TopBar extends React.Component { , -- cgit v1.2.3 From 63ffdb3895caa641881eecf21563a667f6d8b605 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 18:52:51 +0100 Subject: Improve key --- packages/react-docs/src/components/interface.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/react-docs/src/components/interface.tsx b/packages/react-docs/src/components/interface.tsx index 9f0800d71..cad7d6c46 100644 --- a/packages/react-docs/src/components/interface.tsx +++ b/packages/react-docs/src/components/interface.tsx @@ -20,9 +20,9 @@ export interface InterfaceProps { export const Interface: React.SFC = (props: InterfaceProps): any => { const type = props.type; - const properties = _.map(type.children, property => { + const properties = _.map(type.children, (property, i) => { return ( - + {property.name}:{' '} {property.type && !_.isUndefined(property.type.method) ? ( Date: Thu, 27 Sep 2018 18:55:01 +0100 Subject: Render fallback functions better --- packages/react-docs/src/components/signature.tsx | 4 +++- packages/react-docs/src/components/signature_block.tsx | 9 ++++++--- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index a690a1f03..aa174042c 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -19,12 +19,14 @@ export interface SignatureProps { callPath?: string; docsInfo: DocsInfo; isInPopover: boolean; + isFallback?: boolean; } const defaultProps = { shouldHideMethodName: false, shouldUseArrowSyntax: false, callPath: '', + isFallback: false, }; export const Signature: React.SFC = (props: SignatureProps) => { @@ -75,7 +77,7 @@ export const Signature: React.SFC = (props: SignatureProps) => { return ( {props.callPath} - {methodName} + {props.isFallback ? '' : methodName} {typeParameterIfExists}({hasMoreThenTwoParams &&
} {paramStringArray}) {props.returnType && ( diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 1ea0ea28c..fc4db10ad 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -50,6 +50,7 @@ export class SignatureBlock extends React.Component @@ -84,6 +86,7 @@ export class SignatureBlock extends React.Component {(method as TypescriptMethod).source && ( @@ -114,9 +117,9 @@ export class SignatureBlock extends React.Component ); } - private _renderChip(text: string): React.ReactNode { + private _renderChip(text: string, backgroundColor: string = colors.lightBlueA700): React.ReactNode { return ( -
+
{text}
); -- cgit v1.2.3 From a6672e0190573c65f2c36e303d49f0389f5a9a26 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 19:43:10 +0100 Subject: Don't render colon for auto-generated getters --- packages/react-docs/src/components/signature.tsx | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index aa174042c..266bfe3dd 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -118,9 +118,14 @@ function renderParameters( /> ); return ( - + + {!_.isEmpty(p.name) && ( + {p.name} - {isOptional && '?'}: {type} + {isOptional && '?'}:{' '} + + )} + {type} {hasDefaultValue && ` = ${p.defaultValue}`} ); -- cgit v1.2.3 From cfddea931dedb77a88507517957e19350e9348b8 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 19:49:07 +0100 Subject: Make sure basic solidity types are colored orange --- packages/react-docs/src/components/type.tsx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 156a3496d..b7a94483e 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -13,6 +13,7 @@ import { Signature } from './signature'; import { TypeDefinition } from './type_definition'; const basicJsTypes = ['string', 'number', 'undefined', 'null', 'boolean']; +const basicSolidityTypes = ['bytes', 'bytes4', 'uint256', 'address']; const defaultProps = {}; @@ -80,7 +81,7 @@ export const Type: React.SFC = (props: TypeProps): any => { case TypeDocTypes.Array: typeName = type.elementType.name; - if (_.includes(basicJsTypes, typeName)) { + if (_.includes(basicJsTypes, typeName) || _.includes(basicSolidityTypes, typeName)) { typeNameColor = colors.orange; } break; -- cgit v1.2.3 From ac04dbf7e4f04ae4e0a6e9cce5232339597493ed Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 19:50:02 +0100 Subject: Re-use interface component for rendering structs but label it differently --- packages/react-docs/src/components/type_definition.tsx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/react-docs/src/components/type_definition.tsx b/packages/react-docs/src/components/type_definition.tsx index 09cb3ff74..9a3e50a1b 100644 --- a/packages/react-docs/src/components/type_definition.tsx +++ b/packages/react-docs/src/components/type_definition.tsx @@ -5,7 +5,7 @@ import * as _ from 'lodash'; import * as React from 'react'; import { DocsInfo } from '../docs_info'; -import { KindString } from '../types'; +import { KindString, SupportedDocJson } from '../types'; import { constants } from '../utils/constants'; import { Comment } from './comment'; @@ -46,7 +46,7 @@ export class TypeDefinition extends React.Component Date: Thu, 27 Sep 2018 23:00:01 +0100 Subject: Improve keys --- packages/react-docs/src/components/signature.tsx | 6 ++++-- packages/react-docs/src/components/signature_block.tsx | 6 +++--- packages/react-docs/src/components/type.tsx | 6 +++--- 3 files changed, 10 insertions(+), 8 deletions(-) diff --git a/packages/react-docs/src/components/signature.tsx b/packages/react-docs/src/components/signature.tsx index 266bfe3dd..1f3dd0ee8 100644 --- a/packages/react-docs/src/components/signature.tsx +++ b/packages/react-docs/src/components/signature.tsx @@ -36,6 +36,7 @@ export const Signature: React.SFC = (props: SignatureProps) => { props.docsInfo, sectionName, props.isInPopover, + props.name, props.typeDefinitionByName, ); const paramStringArray: any[] = []; @@ -103,9 +104,10 @@ function renderParameters( docsInfo: DocsInfo, sectionName: string, isInPopover: boolean, + name: string, typeDefinitionByName?: TypeDefinitionByName, ): React.ReactNode[] { - const params = _.map(parameters, (p: Parameter) => { + const params = _.map(parameters, (p: Parameter, i: number) => { const isOptional = p.isOptional; const hasDefaultValue = !_.isUndefined(p.defaultValue); const type = ( @@ -121,7 +123,7 @@ function renderParameters( {!_.isEmpty(p.name) && ( - {p.name} + {p.name} {isOptional && '?'}:{' '} )} diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index fc4db10ad..1e3de3e58 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -124,12 +124,12 @@ export class SignatureBlock extends React.Component ); } - private _renderParameterDescriptions(parameters: Parameter[]): React.ReactNode { - const descriptions = _.map(parameters, parameter => { + private _renderParameterDescriptions(parameters: Parameter[], name: string): React.ReactNode { + const descriptions = _.map(parameters, (parameter: Parameter, i: number) => { const isOptional = parameter.isOptional; return (
diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index b7a94483e..8ff2fa3cc 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -169,10 +169,10 @@ export const Type: React.SFC = (props: TypeProps): any => { break; case TypeDocTypes.Tuple: - const tupleTypes = _.map(type.tupleElements, t => { + const tupleTypes = _.map(type.tupleElements, (t, i) => { return ( = (props: TypeProps): any => { const id = Math.random().toString(); const typeDefinitionAnchorId = isExportedClassReference ? props.type.name - : `${constants.TYPES_SECTION_NAME}-${typeName}`; + : `${props.docsInfo.typeSectionName}-${typeName}`; typeName = ( Date: Thu, 27 Sep 2018 23:00:25 +0100 Subject: Only show arguments if the params are named (i.e not generated getters) --- packages/react-docs/src/components/signature_block.tsx | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index 1e3de3e58..cad72daf4 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -32,7 +32,6 @@ export interface SignatureBlockState { const styles: Styles = { chip: { fontSize: 13, - backgroundColor: colors.lightBlueA700, color: colors.white, height: 11, borderRadius: 14, @@ -51,6 +50,7 @@ export class SignatureBlock extends React.Component !_.isEmpty(p.name))); return (
} {method.parameters && - !_.isEmpty(method.parameters) && ( + !_.isEmpty(method.parameters) && + onlyHasNamedParameters && (

ARGUMENTS

- {this._renderParameterDescriptions(method.parameters)} + {this._renderParameterDescriptions(method.parameters, method.name)}
)} {method.returnComment && ( -- cgit v1.2.3 From d4077ae970205f0e41519f95ec5a7ba29cdd105b Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:01:12 +0100 Subject: Fix linter --- packages/sol-doc/src/solidity_doc_generator.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index d2fb5b083..b7b428259 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -117,10 +117,10 @@ function _genDocSection(compiledContract: StandardContractOutput, contractName: // that's because the type of the events array doesn't have any fields for documentation! break; case 'function': - docSection.methods.push(_genMethodDoc(abiDefinition as MethodAbi, compiledContract.devdoc)); + docSection.methods.push(_genMethodDoc(abiDefinition, compiledContract.devdoc)); break; case 'fallback': - docSection.methods.push(_genFallbackDoc(abiDefinition as FallbackAbi, compiledContract.devdoc)); + docSection.methods.push(_genFallbackDoc(abiDefinition, compiledContract.devdoc)); break; default: throw new Error( -- cgit v1.2.3 From 957af23a6422d4010bfa6e3e60e1a8e161a50216 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:02:12 +0100 Subject: Include structs section so that we can render struct params/return values properly with a popover --- packages/sol-doc/package.json | 3 +- packages/sol-doc/src/solidity_doc_generator.ts | 235 ++++++++++++++++++++++--- yarn.lock | 2 +- 3 files changed, 213 insertions(+), 27 deletions(-) diff --git a/packages/sol-doc/package.json b/packages/sol-doc/package.json index 873540215..3b7362b3f 100644 --- a/packages/sol-doc/package.json +++ b/packages/sol-doc/package.json @@ -29,7 +29,8 @@ "@0xproject/utils": "^1.0.11", "ethereum-types": "^1.0.4", "lodash": "^4.17.10", - "yargs": "^12.0.2" + "yargs": "^12.0.2", + "ethereumjs-util": "^5.1.1" }, "devDependencies": { "@0xproject/tslint-config": "^1.0.7", diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index b7b428259..c70f54d5f 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -1,7 +1,5 @@ import * as path from 'path'; -import * as _ from 'lodash'; - import { AbiDefinition, ConstructorAbi, @@ -13,9 +11,13 @@ import { MethodAbi, StandardContractOutput, } from 'ethereum-types'; +import ethUtil = require('ethereumjs-util'); +import * as _ from 'lodash'; import { Compiler, CompilerOptions } from '@0xproject/sol-compiler'; import { + CustomType, + CustomTypeChild, DocAgnosticFormat, DocSection, Event, @@ -26,6 +28,19 @@ import { TypeDocTypes, } from '@0xproject/types'; +// Unforunately, the only way to currently retrieve the declared structs with Solidity contracts +// is to tease it out of the params/return values included in it's ABI. These structures do +// not include the structs actual name, so we needed a mapping to assign the proper name to a +// struct. If the name is not in this mapping, the structs name will default to the param/return value +// name. +const customTypeHashToName: { [hash: string]: string } = { + '52d4a768701076c7bac06e386e430883975eb398732eccba797fd09dd064a60e': 'Order', + '46f7e8c4d144d11a72ce5338458ea37b933500d7a65e740cbca6d16e350eaa48': 'FillResult', + c22239cf0d29df1e6cf1be54f21692a8c0b3a48b9367540d4ffff4608b331ce9: 'OrderInfo', + c21e9ff31a30941c22e1cb43752114bb467c34dea58947f98966c9030fc8e4a9: 'TraderInfo', + '07c2bddc165e0b5005e6244dd4a9771fa61c78c4f42abd687d57567b0768136c': 'MatchedFillResult', +}; + /** * Invoke the Solidity compiler and transform its ABI and devdoc outputs into a * JSON format easily consumed by documentation rendering tools. @@ -41,6 +56,7 @@ export async function generateSolDocAsync( const compilerOptions = _makeCompilerOptions(contractsDir, contractsToDocument); const compiler = new Compiler(compilerOptions); const compilerOutputs = await compiler.getCompilerOutputsAsync(); + let structs: CustomType[] = []; for (const compilerOutput of compilerOutputs) { const contractFileNames = _.keys(compilerOutput.contracts); for (const contractFileName of contractFileNames) { @@ -53,9 +69,12 @@ export async function generateSolDocAsync( throw new Error('compiled contract did not contain ABI output'); } docWithDependencies[contractName] = _genDocSection(compiledContract, contractName); + structs = [...structs, ..._extractStructs(compiledContract)]; } } } + structs = _dedupStructs(structs); + structs = _overwriteStructNames(structs); let doc: DocAgnosticFormat = {}; if (_.isUndefined(contractsToDocument) || contractsToDocument.length === 0) { @@ -71,6 +90,16 @@ export async function generateSolDocAsync( } } + doc.structs = { + comment: '', + constructors: [], + methods: [], + properties: [], + types: structs, + functions: [], + events: [], + }; + return doc; } @@ -95,6 +124,33 @@ function _makeCompilerOptions(contractsDir: string, contractsToCompile?: string[ return compilerOptions; } +function _extractStructs(compiledContract: StandardContractOutput): CustomType[] { + let customTypes: CustomType[] = []; + for (const abiDefinition of compiledContract.abi) { + switch (abiDefinition.type) { + case 'constructor': { + const types = _getStructsAsCustomTypes(abiDefinition); + customTypes = [...customTypes, ...types]; + break; + } + case 'function': { + const types = _getStructsAsCustomTypes(abiDefinition); + customTypes = [...customTypes, ...types]; + break; + } + case 'event': + case 'fallback': + // No types exist + break; + default: + throw new Error( + `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`, + ); + } + } + return customTypes; +} + function _genDocSection(compiledContract: StandardContractOutput, contractName: string): DocSection { const docSection: DocSection = { comment: _.isUndefined(compiledContract.devdoc) ? '' : compiledContract.devdoc.title, @@ -176,7 +232,7 @@ function _devdocMethodDetailsIfExist( } function _genFallbackDoc(abiDefinition: FallbackAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { - const methodSignature = `${name}()`; + const methodSignature = `()`; const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); const returnComment = @@ -186,7 +242,7 @@ function _genFallbackDoc(abiDefinition: FallbackAbi, devdocIfExists: DevdocOutpu const methodDoc: SolidityMethod = { isConstructor: false, - name: '', + name: 'fallback', callPath: '', parameters: [], returnType: { name: 'void', typeDocType: TypeDocTypes.Intrinsic }, @@ -194,23 +250,32 @@ function _genFallbackDoc(abiDefinition: FallbackAbi, devdocIfExists: DevdocOutpu isConstant: true, isPayable: abiDefinition.payable, isFallback: true, - comment, + comment: _.isEmpty(comment) + ? 'The default fallback function. It is executed on a call to the contract if none of the other functions match the given function identifier (or if no data was supplied at all).' + : comment, }; return methodDoc; } function _genMethodDoc(abiDefinition: MethodAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { + const name = abiDefinition.name; const { parameters, methodSignature } = _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists); - const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); - const returnType = _genMethodReturnTypeDoc(abiDefinition.outputs, methodSignature, devdocIfExists); + const devDocComment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); + const returnType = _genMethodReturnTypeDoc(abiDefinition.outputs); const returnComment = _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature]) ? undefined : devdocIfExists.methods[methodSignature].return; + const hasNoNamedParameters = _.isUndefined(_.find(parameters, p => !_.isEmpty(p.name))); + const isGeneratedGetter = hasNoNamedParameters; + const comment = + _.isEmpty(devDocComment) && isGeneratedGetter + ? `This is an auto-generated accessor method of the '${name}' contract instance variable.` + : devDocComment; const methodDoc: SolidityMethod = { isConstructor: false, - name: abiDefinition.name, + name, callPath: '', parameters, returnType, @@ -262,11 +327,13 @@ function _genMethodParamsDoc( ): { parameters: Parameter[]; methodSignature: string } { const parameters: Parameter[] = []; for (const abiParam of abiParams) { + const type = _getTypeFromDataItem(abiParam); + 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 }, + type, }; parameters.push(parameter); } @@ -292,25 +359,143 @@ function _genMethodParamsDoc( return { parameters, methodSignature }; } -function _genMethodReturnTypeDoc( - outputs: DataItem[], - methodSignature: string, - devdocIfExists: DevdocOutput | undefined, -): Type { - const methodReturnTypeDoc: Type = { - name: 'void', - typeDocType: TypeDocTypes.Intrinsic, - tupleElements: undefined, - }; +function _genMethodReturnTypeDoc(outputs: DataItem[]): Type { if (outputs.length > 1) { - methodReturnTypeDoc.typeDocType = TypeDocTypes.Tuple; - methodReturnTypeDoc.tupleElements = []; + const type: Type = { + name: '', + typeDocType: TypeDocTypes.Tuple, + tupleElements: [], + }; for (const output of outputs) { - methodReturnTypeDoc.tupleElements.push({ name: output.type, typeDocType: TypeDocTypes.Intrinsic }); + const tupleType = _getTypeFromDataItem(output); + (type.tupleElements as Type[]).push(tupleType); } + return type; } else if (outputs.length === 1) { - methodReturnTypeDoc.typeDocType = TypeDocTypes.Intrinsic; - methodReturnTypeDoc.name = outputs[0].type; + const output = outputs[0]; + const type = _getTypeFromDataItem(output); + return type; + } else { + const type: Type = { + name: 'void', + typeDocType: TypeDocTypes.Intrinsic, + }; + return type; + } +} + +function _capitalize(text: string): string { + return `${text.charAt(0).toUpperCase()}${text.slice(1)}`; +} + +function _dedupStructs(customTypes: CustomType[]): CustomType[] { + const uniqueCustomTypes: CustomType[] = []; + const seenTypes: { [hash: string]: boolean } = {}; + _.each(customTypes, customType => { + const hash = _generateCustomTypeHash(customType); + if (!seenTypes[hash]) { + uniqueCustomTypes.push(customType); + seenTypes[hash] = true; + } + }); + return uniqueCustomTypes; +} + +function _overwriteStructNames(customTypes: CustomType[]): CustomType[] { + const localCustomTypes = _.cloneDeep(customTypes); + _.each(localCustomTypes, customType => { + const hash = _generateCustomTypeHash(customType); + if (!_.isUndefined(customTypeHashToName[hash])) { + customType.name = customTypeHashToName[hash]; + } + }); + return localCustomTypes; +} + +function _generateCustomTypeHash(customType: CustomType): string { + const customTypeWithoutName = _.cloneDeep(customType); + delete customTypeWithoutName.name; + const customTypeWithoutNameStr = JSON.stringify(customTypeWithoutName); + const hash = ethUtil.sha256(customTypeWithoutNameStr).toString('hex'); + return hash; +} + +function _getStructsAsCustomTypes(abiDefinition: AbiDefinition): CustomType[] { + const customTypes: CustomType[] = []; + if (!_.isUndefined((abiDefinition as any).inputs)) { + const methodOrConstructorAbi = abiDefinition as MethodAbi | ConstructorAbi; + _.each(methodOrConstructorAbi.inputs, input => { + if (!_.isUndefined(input.components)) { + const customType = _getCustomTypeFromDataItem(input); + customTypes.push(customType); + } + }); + } + if (!_.isUndefined((abiDefinition as any).outputs)) { + const methodAbi = abiDefinition as MethodAbi; + _.each(methodAbi.outputs, output => { + if (!_.isUndefined(output.components)) { + const customType = _getCustomTypeFromDataItem(output); + customTypes.push(customType); + } + }); + } + return customTypes; +} + +function _getCustomTypeFromDataItem(inputOrOutput: DataItem): CustomType { + const customType: CustomType = { + name: _.capitalize(inputOrOutput.name), + kindString: 'Interface', + children: [], + }; + _.each(inputOrOutput.components, (component: DataItem) => { + const childType = _getTypeFromDataItem(component); + const customTypeChild = { + name: component.name, + type: childType, + }; + // (fabio): Not sure why this type casting is necessary. Seems TS doesn't + // deduce that `customType.children` cannot be undefined anymore after being + // set to `[]` above. + (customType.children as CustomTypeChild[]).push(customTypeChild); + }); + return customType; +} + +function _getNameFromDataItemIfExists(dataItem: DataItem): string | undefined { + if (_.isUndefined(dataItem.components)) { + return undefined; + } + const customType = _getCustomTypeFromDataItem(dataItem); + const hash = _generateCustomTypeHash(customType); + if (_.isUndefined(customTypeHashToName[hash])) { + return undefined; + } + return customTypeHashToName[hash]; +} + +function _getTypeFromDataItem(dataItem: DataItem): Type { + const typeDocType = !_.isUndefined(dataItem.components) ? TypeDocTypes.Reference : TypeDocTypes.Intrinsic; + let typeName: string; + if (typeDocType === TypeDocTypes.Reference) { + const nameIfExists = _getNameFromDataItemIfExists(dataItem); + typeName = _.isUndefined(nameIfExists) ? _capitalize(dataItem.name) : nameIfExists; + } else { + typeName = dataItem.type; + } + + const isArrayType = _.endsWith(dataItem.type, '[]'); + let type: Type; + if (isArrayType) { + typeName = typeDocType === TypeDocTypes.Intrinsic ? typeName.slice(0, -2) : typeName; + type = { + elementType: { name: typeName, typeDocType }, + typeDocType: TypeDocTypes.Array, + name: '', + }; + } else { + type = { name: typeName, typeDocType }; } - return methodReturnTypeDoc; + return type; } diff --git a/yarn.lock b/yarn.lock index e364c835b..bfc98dabd 100644 --- a/yarn.lock +++ b/yarn.lock @@ -6069,7 +6069,7 @@ ganache-core@0xProject/ganache-core#monorepo-dep: ethereumjs-tx "0xProject/ethereumjs-tx#fake-tx-include-signature-by-default" ethereumjs-util "^5.2.0" ethereumjs-vm "2.3.5" - ethereumjs-wallet "~0.6.0" + ethereumjs-wallet "0.6.0" fake-merkle-patricia-tree "~1.0.1" heap "~0.2.6" js-scrypt "^0.2.0" -- cgit v1.2.3 From 37ab789e841013a556c88418ddd1d5ae38f2b521 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:14:34 +0100 Subject: Remove excessive type --- packages/react-docs/src/components/documentation.tsx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index f1cb32b68..f7feb7717 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -10,7 +10,6 @@ import { utils as sharedUtils, } from '@0xproject/react-shared'; import { - CustomType, DocAgnosticFormat, Event, ExternalExportToLink, @@ -219,7 +218,7 @@ export class Documentation extends React.Component { + const typeDefs = _.map(sortedTypes, (customType, i) => { return ( Date: Thu, 27 Sep 2018 23:16:55 +0100 Subject: Alphabetize --- packages/sol-doc/package.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/sol-doc/package.json b/packages/sol-doc/package.json index 3b7362b3f..8c9590bf3 100644 --- a/packages/sol-doc/package.json +++ b/packages/sol-doc/package.json @@ -28,9 +28,9 @@ "@0xproject/types": "^1.1.1", "@0xproject/utils": "^1.0.11", "ethereum-types": "^1.0.4", + "ethereumjs-util": "^5.1.1", "lodash": "^4.17.10", - "yargs": "^12.0.2", - "ethereumjs-util": "^5.1.1" + "yargs": "^12.0.2" }, "devDependencies": { "@0xproject/tslint-config": "^1.0.7", -- cgit v1.2.3 From 95e84aae49d86ed8edf286bc8c95214f5b2456c7 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:18:32 +0100 Subject: Improve comment --- packages/sol-doc/src/solidity_doc_generator.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index c70f54d5f..1e9c7d5d7 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -28,11 +28,11 @@ import { TypeDocTypes, } from '@0xproject/types'; -// Unforunately, the only way to currently retrieve the declared structs with Solidity contracts -// is to tease it out of the params/return values included in it's ABI. These structures do -// not include the structs actual name, so we needed a mapping to assign the proper name to a +// Unforunately, the only way to currently retrieve the declared structs within Solidity contracts +// is to tease them out of the params/return values included in the ABI. These structures do +// not include the structs actual name, so we need a mapping to assign the proper name to a // struct. If the name is not in this mapping, the structs name will default to the param/return value -// name. +// name (which mostly coincide). const customTypeHashToName: { [hash: string]: string } = { '52d4a768701076c7bac06e386e430883975eb398732eccba797fd09dd064a60e': 'Order', '46f7e8c4d144d11a72ce5338458ea37b933500d7a65e740cbca6d16e350eaa48': 'FillResult', -- cgit v1.2.3 From e0ff3484cf169162f3a339b6cb779fa2b562ad73 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:20:21 +0100 Subject: Improve switch case --- packages/sol-doc/src/solidity_doc_generator.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index 1e9c7d5d7..09e78aef2 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -127,15 +127,14 @@ function _makeCompilerOptions(contractsDir: string, contractsToCompile?: string[ function _extractStructs(compiledContract: StandardContractOutput): CustomType[] { let customTypes: CustomType[] = []; for (const abiDefinition of compiledContract.abi) { + let types: CustomType[] = []; switch (abiDefinition.type) { case 'constructor': { - const types = _getStructsAsCustomTypes(abiDefinition); - customTypes = [...customTypes, ...types]; + types = _getStructsAsCustomTypes(abiDefinition); break; } case 'function': { - const types = _getStructsAsCustomTypes(abiDefinition); - customTypes = [...customTypes, ...types]; + types = _getStructsAsCustomTypes(abiDefinition); break; } case 'event': @@ -147,6 +146,7 @@ function _extractStructs(compiledContract: StandardContractOutput): CustomType[] `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`, ); } + customTypes = [...customTypes, ...types]; } return customTypes; } -- cgit v1.2.3 From b2ff7bda02c02a950eb2cc656eaa5780d7b71b5b Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:24:05 +0100 Subject: Explain cast to any --- packages/sol-doc/src/solidity_doc_generator.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index 09e78aef2..d441b9a23 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -422,6 +422,8 @@ function _generateCustomTypeHash(customType: CustomType): string { function _getStructsAsCustomTypes(abiDefinition: AbiDefinition): CustomType[] { const customTypes: CustomType[] = []; + // We cast to `any` here because we do not know yet if this type of abiDefinition contains + // an `input` key if (!_.isUndefined((abiDefinition as any).inputs)) { const methodOrConstructorAbi = abiDefinition as MethodAbi | ConstructorAbi; _.each(methodOrConstructorAbi.inputs, input => { -- cgit v1.2.3 From 092b184f4534a42d36d30d2d10b34b47255d2ee3 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:30:11 +0100 Subject: Fix linter --- packages/react-docs/src/components/signature_block.tsx | 4 ++-- packages/react-docs/src/components/type.tsx | 1 - packages/sol-doc/src/solidity_doc_generator.ts | 2 ++ 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/packages/react-docs/src/components/signature_block.tsx b/packages/react-docs/src/components/signature_block.tsx index cad72daf4..5ec82983a 100644 --- a/packages/react-docs/src/components/signature_block.tsx +++ b/packages/react-docs/src/components/signature_block.tsx @@ -50,7 +50,7 @@ export class SignatureBlock extends React.Component !_.isEmpty(p.name))); + const hasExclusivelyNamedParams = !_.isUndefined(_.find(method.parameters, p => !_.isEmpty(p.name))); return (
} {method.parameters && !_.isEmpty(method.parameters) && - onlyHasNamedParameters && ( + hasExclusivelyNamedParams && (

ARGUMENTS diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 8ff2fa3cc..028376ba9 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -7,7 +7,6 @@ import { Link as ScrollLink } from 'react-scroll'; import * as ReactTooltip from 'react-tooltip'; import { DocsInfo } from '../docs_info'; -import { constants } from '../utils/constants'; import { Signature } from './signature'; import { TypeDefinition } from './type_definition'; diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index d441b9a23..362fe12c3 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -490,6 +490,7 @@ function _getTypeFromDataItem(dataItem: DataItem): Type { const isArrayType = _.endsWith(dataItem.type, '[]'); let type: Type; if (isArrayType) { + // tslint:disable-next-line:custom-no-magic-numbers typeName = typeDocType === TypeDocTypes.Intrinsic ? typeName.slice(0, -2) : typeName; type = { elementType: { name: typeName, typeDocType }, @@ -501,3 +502,4 @@ function _getTypeFromDataItem(dataItem: DataItem): Type { } return type; } +// tslint:disable:max-file-line-count -- cgit v1.2.3 From 8531f52456169d6b2103757e8e511710c58a54d0 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Thu, 27 Sep 2018 23:32:29 +0100 Subject: Switch over remaining usage of `sections.types` for `typeSectionName` --- packages/react-docs/src/docs_info.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/react-docs/src/docs_info.ts b/packages/react-docs/src/docs_info.ts index bf6aa07a7..092a8c266 100644 --- a/packages/react-docs/src/docs_info.ts +++ b/packages/react-docs/src/docs_info.ts @@ -84,11 +84,11 @@ export class DocsInfo { return menuSubsectionsBySection; } public getTypeDefinitionsByName(docAgnosticFormat: DocAgnosticFormat): { [name: string]: TypeDefinitionByName } { - if (_.isUndefined(this.sections.types)) { + if (_.isUndefined(docAgnosticFormat[this.typeSectionName])) { return {}; } - const section = docAgnosticFormat[this.sections.types]; + const section = docAgnosticFormat[this.typeSectionName]; const typeDefinitionByName = _.keyBy(section.types, 'name') as any; return typeDefinitionByName; } -- cgit v1.2.3 From 144561c53be3df1e03cd46de23cec4710056907a Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 10:28:57 +0100 Subject: Fix missing devdoc comments in output by fixing improper encoding of methodSignatures --- packages/sol-doc/src/solidity_doc_generator.ts | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index 362fe12c3..09137c4cf 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -340,7 +340,16 @@ function _genMethodParamsDoc( const methodSignature = `${name}(${abiParams .map(abiParam => { - return abiParam.type; + if (!_.startsWith(abiParam.type, 'tuple')) { + return abiParam.type; + } else { + // Need to expand tuples: + // E.g: fillOrder(tuple,uint256,bytes) -> fillOrder((address,address,address,address,uint256,uint256,uint256,uint256,uint256,uint256,bytes,bytes),uint256,bytes) + const isArray = _.endsWith(abiParam.type, '[]'); + const expandedTypes = _.map(abiParam.components, c => c.type); + const type = `(${expandedTypes.join(',')})${isArray ? '[]' : ''}`; + return type; + } }) .join(',')})`; -- cgit v1.2.3 From 28f5cd06418e52a80fb784dbed75120d76b4204b Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 10:30:24 +0100 Subject: Only add Stucts section if there are any --- packages/sol-doc/src/solidity_doc_generator.ts | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts index 09137c4cf..424577411 100644 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ b/packages/sol-doc/src/solidity_doc_generator.ts @@ -90,15 +90,17 @@ export async function generateSolDocAsync( } } - doc.structs = { - comment: '', - constructors: [], - methods: [], - properties: [], - types: structs, - functions: [], - events: [], - }; + if (structs.length > 0) { + doc.structs = { + comment: '', + constructors: [], + methods: [], + properties: [], + types: structs, + functions: [], + events: [], + }; + } return doc; } -- cgit v1.2.3 From 545472a38fabfd8a18cb03a23ae02f99917f0f4c Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 10:50:55 +0100 Subject: Fix section headers --- packages/react-docs/src/components/documentation.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index f7feb7717..df727ad9c 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -265,7 +265,7 @@ export class Documentation extends React.Component
- +
{this._renderNetworkBadgesIfExists(sectionName)}
-- cgit v1.2.3 From 398b2926366bfabc4decca48dd24c85c466c48ed Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 11:04:51 +0100 Subject: Add more basic types --- packages/react-docs/src/components/type.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-docs/src/components/type.tsx b/packages/react-docs/src/components/type.tsx index 028376ba9..5c018f5dd 100644 --- a/packages/react-docs/src/components/type.tsx +++ b/packages/react-docs/src/components/type.tsx @@ -12,7 +12,7 @@ import { Signature } from './signature'; import { TypeDefinition } from './type_definition'; const basicJsTypes = ['string', 'number', 'undefined', 'null', 'boolean']; -const basicSolidityTypes = ['bytes', 'bytes4', 'uint256', 'address']; +const basicSolidityTypes = ['bytes', 'bytes4', 'bytes32', 'uint8', 'uint256', 'address']; const defaultProps = {}; -- cgit v1.2.3 From 6dff24906edad6d603bddcb8359349b20f5e3009 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 11:05:13 +0100 Subject: Fix network badges for V1 and add them for V2 --- .../ts/containers/smart_contracts_documentation.ts | 60 ++++++++++++++++------ 1 file changed, 44 insertions(+), 16 deletions(-) diff --git a/packages/website/ts/containers/smart_contracts_documentation.ts b/packages/website/ts/containers/smart_contracts_documentation.ts index 8d69afe71..05b2a50c3 100644 --- a/packages/website/ts/containers/smart_contracts_documentation.ts +++ b/packages/website/ts/containers/smart_contracts_documentation.ts @@ -37,28 +37,56 @@ const docsInfoConfig: DocsInfoConfig = { contractsByVersionByNetworkId: { '1.0.0': { [Networks.Mainnet]: { - [Sections.Exchange]: '0x12459c951127e0c374ff9105dda097662a027093', - [Sections.TokenTransferProxy]: '0x8da0d80f5007ef1e431dd2127178d224e32c2ef4', - [Sections.ZRXToken]: '0xe41d2489571d322189246dafa5ebde1f4699f498', - [Sections.TokenRegistry]: '0x926a74c5c36adf004c87399e65f75628b0f98d2c', + Exchange_v1: '0x12459c951127e0c374ff9105dda097662a027093', + TokenTransferProxy_v1: '0x8da0d80f5007ef1e431dd2127178d224e32c2ef4', + TokenRegistry: '0x926a74c5c36adf004c87399e65f75628b0f98d2c', }, [Networks.Ropsten]: { - [Sections.Exchange]: '0x479cc461fecd078f766ecc58533d6f69580cf3ac', - [Sections.TokenTransferProxy]: '0x4e9aad8184de8833365fea970cd9149372fdf1e6', - [Sections.ZRXToken]: '0xa8e9fa8f91e5ae138c74648c9c304f1c75003a8d', - [Sections.TokenRegistry]: '0x6b1a50f0bb5a7995444bd3877b22dc89c62843ed', + Exchange_v1: '0x479cc461fecd078f766ecc58533d6f69580cf3ac', + TokenTransferProxy_v1: '0x4e9aad8184de8833365fea970cd9149372fdf1e6', + TokenRegistry: '0x6b1a50f0bb5a7995444bd3877b22dc89c62843ed', }, [Networks.Kovan]: { - [Sections.Exchange]: '0x90fe2af704b34e0224bf2299c838e04d4dcf1364', - [Sections.TokenTransferProxy]: '0x087Eed4Bc1ee3DE49BeFbd66C662B434B15d49d4', - [Sections.ZRXToken]: '0x6ff6c0ff1d68b964901f986d4c9fa3ac68346570', - [Sections.TokenRegistry]: '0xf18e504561f4347bea557f3d4558f559dddbae7f', + Exchange_v1: '0x90fe2af704b34e0224bf2299c838e04d4dcf1364', + TokenTransferProxy_v1: '0x087Eed4Bc1ee3DE49BeFbd66C662B434B15d49d4', + TokenRegistry: '0xf18e504561f4347bea557f3d4558f559dddbae7f', }, [Networks.Rinkeby]: { - [Sections.Exchange]: '0x1d16ef40fac01cec8adac2ac49427b9384192c05', - [Sections.TokenTransferProxy]: '0xa8e9fa8f91e5ae138c74648c9c304f1c75003a8d', - [Sections.ZRXToken]: '0x00f58d6d585f84b2d7267940cede30ce2fe6eae8', - [Sections.TokenRegistry]: '0x4e9aad8184de8833365fea970cd9149372fdf1e6', + Exchange_v1: '0x1d16ef40fac01cec8adac2ac49427b9384192c05', + TokenTransferProxy_v1: '0xa8e9fa8f91e5ae138c74648c9c304f1c75003a8d', + TokenRegistry: '0x4e9aad8184de8833365fea970cd9149372fdf1e6', + }, + }, + '2.0.0': { + [Networks.Mainnet]: { + AssetProxyOwner: '0x17992e4ffb22730138e4b62aaa6367fa9d3699a6', + ERC20Proxy: '0x2240dab907db71e64d3e0dba4800c83b5c502d4e', + ERC721Proxy: '0x208e41fb445f1bb1b6780d58356e81405f3e6127', + Exchange: '0x4f833a24e1f95d70f028921e27040ca56e09ab0b', + Forwarder: '0x7afc2d5107af94c462a194d2c21b5bdd238709d6', + OrderValidator: '0x9463e518dea6810309563c81d5266c1b1d149138', + WETH9: '0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2', + ZRXToken: '0xe41d2489571d322189246dafa5ebde1f4699f498', + }, + [Networks.Ropsten]: { + AssetProxyOwner: '0xf5fa5b5fed2727a0e44ac67f6772e97977aa358b', + ERC20Proxy: '0xb1408f4c245a23c31b98d2c626777d4c0d766caa', + ERC721Proxy: '0xe654aac058bfbf9f83fcaee7793311dd82f6ddb4', + Exchange: '0x4530c0483a1633c7a1c97d2c53721caff2caaaaf', + Forwarder: '0x3983e204b12b3c02fb0638caf2cd406a62e0ead3', + OrderValidator: '0x90431a90516ab49af23a0530e04e8c7836e7122f', + WETH9: '0xc778417e063141139fce010982780140aa0cd5ab', + ZRXToken: '0xff67881f8d12f372d91baae9752eb3631ff0ed00', + }, + [Networks.Kovan]: { + AssetProxyOwner: '0x2c824d2882baa668e0d5202b1e7f2922278703f8', + ERC20Proxy: '0xf1ec01d6236d3cd881a0bf0130ea25fe4234003e', + ERC721Proxy: '0x2a9127c745688a165106c11cd4d647d2220af821', + Exchange: '0x35dd2932454449b14cee11a94d3674a936d5d7b2', + Forwarder: '0xd85e2fa7e7e252b27b01bf0d65c946959d2f45b8', + OrderValidator: '0xb389da3d204b412df2f75c6afb3d0a7ce0bc283d', + WETH9: '0xd0a1e359811322d97991e03f863a0c30c2cf029c', + ZRXToken: '0x2002d3812f58e35f0ea1ffbf80a75a38c32175fa', }, }, }, -- cgit v1.2.3 From 005a2e12bac3e0ca8762f627ec5e9df6d2991d6e Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 11:33:30 +0100 Subject: Fix badge alignment --- packages/react-docs/src/components/documentation.tsx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/react-docs/src/components/documentation.tsx b/packages/react-docs/src/components/documentation.tsx index df727ad9c..a23111297 100644 --- a/packages/react-docs/src/components/documentation.tsx +++ b/packages/react-docs/src/components/documentation.tsx @@ -353,7 +353,7 @@ export class Documentation extends React.Component -- cgit v1.2.3 From 9ae60d0abe0ea32eb9dbfc48a9168d1996c674a0 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 17:20:24 +0100 Subject: Export class instead of function --- packages/sol-doc/src/cli.ts | 17 +- packages/sol-doc/src/index.ts | 2 +- packages/sol-doc/src/sol_doc.ts | 500 ++++++++++++++++++++ packages/sol-doc/src/solidity_doc_generator.ts | 516 --------------------- .../sol-doc/test/solidity_doc_generator_test.ts | 20 +- 5 files changed, 529 insertions(+), 526 deletions(-) create mode 100644 packages/sol-doc/src/sol_doc.ts delete mode 100644 packages/sol-doc/src/solidity_doc_generator.ts diff --git a/packages/sol-doc/src/cli.ts b/packages/sol-doc/src/cli.ts index eb0f00bf6..04956510e 100644 --- a/packages/sol-doc/src/cli.ts +++ b/packages/sol-doc/src/cli.ts @@ -3,7 +3,7 @@ import * as yargs from 'yargs'; import { logUtils } from '@0xproject/utils'; -import { generateSolDocAsync } from './solidity_doc_generator'; +import { SolDoc } from './sol_doc'; const JSON_TAB_WIDTH = 4; @@ -20,7 +20,20 @@ const JSON_TAB_WIDTH = 4; .demandOption('contracts-dir') .array('contracts') .help().argv; - const doc = await generateSolDocAsync(argv.contractsDir, argv.contracts); + // Unforunately, the only way to currently retrieve the declared structs within Solidity contracts + // is to tease them out of the params/return values included in the ABI. These structures do + // not include the structs actual name, so we need a mapping to assign the proper name to a + // struct. If the name is not in this mapping, the structs name will default to the param/return value + // name (which mostly coincide). + const customTypeHashToName: { [hash: string]: string } = { + '52d4a768701076c7bac06e386e430883975eb398732eccba797fd09dd064a60e': 'Order', + '46f7e8c4d144d11a72ce5338458ea37b933500d7a65e740cbca6d16e350eaa48': 'FillResult', + c22239cf0d29df1e6cf1be54f21692a8c0b3a48b9367540d4ffff4608b331ce9: 'OrderInfo', + c21e9ff31a30941c22e1cb43752114bb467c34dea58947f98966c9030fc8e4a9: 'TraderInfo', + '07c2bddc165e0b5005e6244dd4a9771fa61c78c4f42abd687d57567b0768136c': 'MatchedFillResults', + }; + const solDoc = new SolDoc(); + const doc = await solDoc.generateSolDocAsync(argv.contractsDir, argv.contracts, customTypeHashToName); process.stdout.write(JSON.stringify(doc, null, JSON_TAB_WIDTH)); })().catch(err => { logUtils.warn(err); diff --git a/packages/sol-doc/src/index.ts b/packages/sol-doc/src/index.ts index 03f3c9de6..521668cc8 100644 --- a/packages/sol-doc/src/index.ts +++ b/packages/sol-doc/src/index.ts @@ -1 +1 @@ -export { generateSolDocAsync } from './solidity_doc_generator'; +export { SolDoc } from './sol_doc'; diff --git a/packages/sol-doc/src/sol_doc.ts b/packages/sol-doc/src/sol_doc.ts new file mode 100644 index 000000000..4b7cbe77c --- /dev/null +++ b/packages/sol-doc/src/sol_doc.ts @@ -0,0 +1,500 @@ +import * as path from 'path'; + +import { + AbiDefinition, + ConstructorAbi, + DataItem, + DevdocOutput, + EventAbi, + EventParameter, + FallbackAbi, + MethodAbi, + StandardContractOutput, +} from 'ethereum-types'; +import ethUtil = require('ethereumjs-util'); +import * as _ from 'lodash'; + +import { Compiler, CompilerOptions } from '@0xproject/sol-compiler'; +import { + CustomType, + CustomTypeChild, + DocAgnosticFormat, + DocSection, + Event, + EventArg, + ObjectMap, + Parameter, + SolidityMethod, + Type, + TypeDocTypes, +} from '@0xproject/types'; + +export class SolDoc { + private _customTypeHashToName: ObjectMap | undefined; + private static _genEventDoc(abiDefinition: EventAbi): Event { + const eventDoc: Event = { + name: abiDefinition.name, + eventArgs: SolDoc._genEventArgsDoc(abiDefinition.inputs), + }; + return eventDoc; + } + private static _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; + } + private static _genFallbackDoc( + abiDefinition: FallbackAbi, + devdocIfExists: DevdocOutput | undefined, + ): SolidityMethod { + const methodSignature = `()`; + const comment = SolDoc._devdocMethodDetailsIfExist(methodSignature, devdocIfExists); + + const returnComment = + _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature]) + ? undefined + : devdocIfExists.methods[methodSignature].return; + + const methodDoc: SolidityMethod = { + isConstructor: false, + name: 'fallback', + callPath: '', + parameters: [], + returnType: { name: 'void', typeDocType: TypeDocTypes.Intrinsic }, + returnComment, + isConstant: true, + isPayable: abiDefinition.payable, + isFallback: true, + comment: _.isEmpty(comment) + ? 'The fallback function. It is executed on a call to the contract if none of the other functions match the given public identifier (or if no data was supplied at all).' + : comment, + }; + return methodDoc; + } + private static _genEventArgsDoc(args: EventParameter[]): 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; + } + private static _dedupStructs(customTypes: CustomType[]): CustomType[] { + const uniqueCustomTypes: CustomType[] = []; + const seenTypes: { [hash: string]: boolean } = {}; + _.each(customTypes, customType => { + const hash = SolDoc._generateCustomTypeHash(customType); + if (!seenTypes[hash]) { + uniqueCustomTypes.push(customType); + seenTypes[hash] = true; + } + }); + return uniqueCustomTypes; + } + private static _capitalize(text: string): string { + return `${text.charAt(0).toUpperCase()}${text.slice(1)}`; + } + private static _generateCustomTypeHash(customType: CustomType): string { + const customTypeWithoutName = _.cloneDeep(customType); + delete customTypeWithoutName.name; + const customTypeWithoutNameStr = JSON.stringify(customTypeWithoutName); + const hash = ethUtil.sha256(customTypeWithoutNameStr).toString('hex'); + return hash; + } + private static _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; + } + /** + * 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. + */ + public async generateSolDocAsync( + contractsDir: string, + contractsToDocument?: string[], + customTypeHashToName?: ObjectMap, + ): Promise { + this._customTypeHashToName = customTypeHashToName; + const docWithDependencies: DocAgnosticFormat = {}; + const compilerOptions = SolDoc._makeCompilerOptions(contractsDir, contractsToDocument); + const compiler = new Compiler(compilerOptions); + const compilerOutputs = await compiler.getCompilerOutputsAsync(); + let structs: CustomType[] = []; + 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] = this._genDocSection(compiledContract, contractName); + structs = [...structs, ...this._extractStructs(compiledContract)]; + } + } + } + structs = SolDoc._dedupStructs(structs); + structs = this._overwriteStructNames(structs); + + 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]; + } + } + + if (structs.length > 0) { + doc.structs = { + comment: '', + constructors: [], + methods: [], + properties: [], + types: structs, + functions: [], + events: [], + }; + } + + delete this._customTypeHashToName; // Clean up instance state + return doc; + } + private _getCustomTypeFromDataItem(inputOrOutput: DataItem): CustomType { + const customType: CustomType = { + name: _.capitalize(inputOrOutput.name), + kindString: 'Interface', + children: [], + }; + _.each(inputOrOutput.components, (component: DataItem) => { + const childType = this._getTypeFromDataItem(component); + const customTypeChild = { + name: component.name, + type: childType, + }; + // (fabio): Not sure why this type casting is necessary. Seems TS doesn't + // deduce that `customType.children` cannot be undefined anymore after being + // set to `[]` above. + (customType.children as CustomTypeChild[]).push(customTypeChild); + }); + return customType; + } + private _getNameFromDataItemIfExists(dataItem: DataItem): string | undefined { + if (_.isUndefined(dataItem.components)) { + return undefined; + } + const customType = this._getCustomTypeFromDataItem(dataItem); + const hash = SolDoc._generateCustomTypeHash(customType); + if (_.isUndefined(this._customTypeHashToName) || _.isUndefined(this._customTypeHashToName[hash])) { + return undefined; + } + return this._customTypeHashToName[hash]; + } + private _getTypeFromDataItem(dataItem: DataItem): Type { + const typeDocType = !_.isUndefined(dataItem.components) ? TypeDocTypes.Reference : TypeDocTypes.Intrinsic; + let typeName: string; + if (typeDocType === TypeDocTypes.Reference) { + const nameIfExists = this._getNameFromDataItemIfExists(dataItem); + typeName = _.isUndefined(nameIfExists) ? SolDoc._capitalize(dataItem.name) : nameIfExists; + } else { + typeName = dataItem.type; + } + + const isArrayType = _.endsWith(dataItem.type, '[]'); + let type: Type; + if (isArrayType) { + // tslint:disable-next-line:custom-no-magic-numbers + typeName = typeDocType === TypeDocTypes.Intrinsic ? typeName.slice(0, -2) : typeName; + type = { + elementType: { name: typeName, typeDocType }, + typeDocType: TypeDocTypes.Array, + name: '', + }; + } else { + type = { name: typeName, typeDocType }; + } + return type; + } + private _overwriteStructNames(customTypes: CustomType[], customTypeHashToName?: ObjectMap): CustomType[] { + if (_.isUndefined(customTypeHashToName)) { + return customTypes; + } + const localCustomTypes = _.cloneDeep(customTypes); + _.each(localCustomTypes, customType => { + const hash = SolDoc._generateCustomTypeHash(customType); + if (!_.isUndefined(this._customTypeHashToName) && !_.isUndefined(this._customTypeHashToName[hash])) { + customType.name = this._customTypeHashToName[hash]; + } + }); + return localCustomTypes; + } + private _extractStructs(compiledContract: StandardContractOutput): CustomType[] { + let customTypes: CustomType[] = []; + for (const abiDefinition of compiledContract.abi) { + let types: CustomType[] = []; + switch (abiDefinition.type) { + case 'constructor': { + types = this._getStructsAsCustomTypes(abiDefinition); + break; + } + case 'function': { + types = this._getStructsAsCustomTypes(abiDefinition); + break; + } + case 'event': + case 'fallback': + // No types exist + break; + default: + throw new Error( + `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`, + ); + } + customTypes = [...customTypes, ...types]; + } + return customTypes; + } + private _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( + this._genConstructorDoc(contractName, abiDefinition, compiledContract.devdoc), + ); + break; + case 'event': + (docSection.events as Event[]).push(SolDoc._genEventDoc(abiDefinition)); + // note that we're not sending devdoc to this._genEventDoc(). + // that's because the type of the events array doesn't have any fields for documentation! + break; + case 'function': + docSection.methods.push(this._genMethodDoc(abiDefinition, compiledContract.devdoc)); + break; + case 'fallback': + docSection.methods.push(SolDoc._genFallbackDoc(abiDefinition, compiledContract.devdoc)); + break; + default: + throw new Error( + `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`, + ); + } + } + + return docSection; + } + private _genConstructorDoc( + contractName: string, + abiDefinition: ConstructorAbi, + devdocIfExists: DevdocOutput | undefined, + ): SolidityMethod { + const { parameters, methodSignature } = this._genMethodParamsDoc('', abiDefinition.inputs, devdocIfExists); + + const comment = SolDoc._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; + } + private _genMethodDoc(abiDefinition: MethodAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { + const name = abiDefinition.name; + const { parameters, methodSignature } = this._genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists); + const devDocComment = SolDoc._devdocMethodDetailsIfExist(methodSignature, devdocIfExists); + const returnType = this._genMethodReturnTypeDoc(abiDefinition.outputs); + const returnComment = + _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature]) + ? undefined + : devdocIfExists.methods[methodSignature].return; + + const hasNoNamedParameters = _.isUndefined(_.find(parameters, p => !_.isEmpty(p.name))); + const isGeneratedGetter = hasNoNamedParameters; + const comment = + _.isEmpty(devDocComment) && isGeneratedGetter + ? `This is an auto-generated accessor method of the '${name}' contract instance variable.` + : devDocComment; + const methodDoc: SolidityMethod = { + isConstructor: false, + name, + callPath: '', + parameters, + returnType, + returnComment, + isConstant: abiDefinition.constant, + isPayable: abiDefinition.payable, + comment, + }; + return methodDoc; + } + /** + * Extract documentation for each method parameter from @param params. + */ + private _genMethodParamsDoc( + name: string, + abiParams: DataItem[], + devdocIfExists: DevdocOutput | undefined, + ): { parameters: Parameter[]; methodSignature: string } { + const parameters: Parameter[] = []; + for (const abiParam of abiParams) { + const type = this._getTypeFromDataItem(abiParam); + + const parameter: Parameter = { + name: abiParam.name, + comment: '', + isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232 + type, + }; + parameters.push(parameter); + } + + const methodSignature = `${name}(${abiParams + .map(abiParam => { + if (!_.startsWith(abiParam.type, 'tuple')) { + return abiParam.type; + } else { + // Need to expand tuples: + // E.g: fillOrder(tuple,uint256,bytes) -> fillOrder((address,address,address,address,uint256,uint256,uint256,uint256,uint256,uint256,bytes,bytes),uint256,bytes) + const isArray = _.endsWith(abiParam.type, '[]'); + const expandedTypes = _.map(abiParam.components, c => c.type); + const type = `(${expandedTypes.join(',')})${isArray ? '[]' : ''}`; + return 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 }; + } + private _genMethodReturnTypeDoc(outputs: DataItem[]): Type { + let type: Type; + if (outputs.length > 1) { + type = { + name: '', + typeDocType: TypeDocTypes.Tuple, + tupleElements: [], + }; + for (const output of outputs) { + const tupleType = this._getTypeFromDataItem(output); + (type.tupleElements as Type[]).push(tupleType); + } + return type; + } else if (outputs.length === 1) { + const output = outputs[0]; + type = this._getTypeFromDataItem(output); + } else { + type = { + name: 'void', + typeDocType: TypeDocTypes.Intrinsic, + }; + } + return type; + } + private _getStructsAsCustomTypes(abiDefinition: AbiDefinition): CustomType[] { + const customTypes: CustomType[] = []; + // We cast to `any` here because we do not know yet if this type of abiDefinition contains + // an `input` key + if (!_.isUndefined((abiDefinition as any).inputs)) { + const methodOrConstructorAbi = abiDefinition as MethodAbi | ConstructorAbi; + _.each(methodOrConstructorAbi.inputs, input => { + if (!_.isUndefined(input.components)) { + const customType = this._getCustomTypeFromDataItem(input); + customTypes.push(customType); + } + }); + } + if (!_.isUndefined((abiDefinition as any).outputs)) { + const methodAbi = abiDefinition as MethodAbi; + _.each(methodAbi.outputs, output => { + if (!_.isUndefined(output.components)) { + const customType = this._getCustomTypeFromDataItem(output); + customTypes.push(customType); + } + }); + } + return customTypes; + } +} +// tslint:disable:max-file-line-count 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 424577411..000000000 --- a/packages/sol-doc/src/solidity_doc_generator.ts +++ /dev/null @@ -1,516 +0,0 @@ -import * as path from 'path'; - -import { - AbiDefinition, - ConstructorAbi, - DataItem, - DevdocOutput, - EventAbi, - EventParameter, - FallbackAbi, - MethodAbi, - StandardContractOutput, -} from 'ethereum-types'; -import ethUtil = require('ethereumjs-util'); -import * as _ from 'lodash'; - -import { Compiler, CompilerOptions } from '@0xproject/sol-compiler'; -import { - CustomType, - CustomTypeChild, - DocAgnosticFormat, - DocSection, - Event, - EventArg, - Parameter, - SolidityMethod, - Type, - TypeDocTypes, -} from '@0xproject/types'; - -// Unforunately, the only way to currently retrieve the declared structs within Solidity contracts -// is to tease them out of the params/return values included in the ABI. These structures do -// not include the structs actual name, so we need a mapping to assign the proper name to a -// struct. If the name is not in this mapping, the structs name will default to the param/return value -// name (which mostly coincide). -const customTypeHashToName: { [hash: string]: string } = { - '52d4a768701076c7bac06e386e430883975eb398732eccba797fd09dd064a60e': 'Order', - '46f7e8c4d144d11a72ce5338458ea37b933500d7a65e740cbca6d16e350eaa48': 'FillResult', - c22239cf0d29df1e6cf1be54f21692a8c0b3a48b9367540d4ffff4608b331ce9: 'OrderInfo', - c21e9ff31a30941c22e1cb43752114bb467c34dea58947f98966c9030fc8e4a9: 'TraderInfo', - '07c2bddc165e0b5005e6244dd4a9771fa61c78c4f42abd687d57567b0768136c': 'MatchedFillResult', -}; - -/** - * 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 { - const docWithDependencies: DocAgnosticFormat = {}; - const compilerOptions = _makeCompilerOptions(contractsDir, contractsToDocument); - const compiler = new Compiler(compilerOptions); - const compilerOutputs = await compiler.getCompilerOutputsAsync(); - let structs: CustomType[] = []; - 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); - structs = [...structs, ..._extractStructs(compiledContract)]; - } - } - } - structs = _dedupStructs(structs); - structs = _overwriteStructNames(structs); - - 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]; - } - } - - if (structs.length > 0) { - doc.structs = { - comment: '', - constructors: [], - methods: [], - properties: [], - types: structs, - functions: [], - events: [], - }; - } - - 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 _extractStructs(compiledContract: StandardContractOutput): CustomType[] { - let customTypes: CustomType[] = []; - for (const abiDefinition of compiledContract.abi) { - let types: CustomType[] = []; - switch (abiDefinition.type) { - case 'constructor': { - types = _getStructsAsCustomTypes(abiDefinition); - break; - } - case 'function': { - types = _getStructsAsCustomTypes(abiDefinition); - break; - } - case 'event': - case 'fallback': - // No types exist - break; - default: - throw new Error( - `unknown and unsupported AbiDefinition type '${(abiDefinition as AbiDefinition).type}'`, - ); - } - customTypes = [...customTypes, ...types]; - } - return customTypes; -} - -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': - docSection.methods.push(_genMethodDoc(abiDefinition, compiledContract.devdoc)); - break; - case 'fallback': - docSection.methods.push(_genFallbackDoc(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 _genFallbackDoc(abiDefinition: FallbackAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { - const methodSignature = `()`; - const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); - - const returnComment = - _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature]) - ? undefined - : devdocIfExists.methods[methodSignature].return; - - const methodDoc: SolidityMethod = { - isConstructor: false, - name: 'fallback', - callPath: '', - parameters: [], - returnType: { name: 'void', typeDocType: TypeDocTypes.Intrinsic }, - returnComment, - isConstant: true, - isPayable: abiDefinition.payable, - isFallback: true, - comment: _.isEmpty(comment) - ? 'The default fallback function. It is executed on a call to the contract if none of the other functions match the given function identifier (or if no data was supplied at all).' - : comment, - }; - return methodDoc; -} - -function _genMethodDoc(abiDefinition: MethodAbi, devdocIfExists: DevdocOutput | undefined): SolidityMethod { - const name = abiDefinition.name; - const { parameters, methodSignature } = _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists); - const devDocComment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists); - const returnType = _genMethodReturnTypeDoc(abiDefinition.outputs); - const returnComment = - _.isUndefined(devdocIfExists) || _.isUndefined(devdocIfExists.methods[methodSignature]) - ? undefined - : devdocIfExists.methods[methodSignature].return; - - const hasNoNamedParameters = _.isUndefined(_.find(parameters, p => !_.isEmpty(p.name))); - const isGeneratedGetter = hasNoNamedParameters; - const comment = - _.isEmpty(devDocComment) && isGeneratedGetter - ? `This is an auto-generated accessor method of the '${name}' contract instance variable.` - : devDocComment; - const methodDoc: SolidityMethod = { - isConstructor: false, - name, - callPath: '', - parameters, - returnType, - returnComment, - isConstant: abiDefinition.constant, - 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 type = _getTypeFromDataItem(abiParam); - - const parameter: Parameter = { - name: abiParam.name, - comment: '', - isOptional: false, // Unsupported in Solidity, until resolution of https://github.com/ethereum/solidity/issues/232 - type, - }; - parameters.push(parameter); - } - - const methodSignature = `${name}(${abiParams - .map(abiParam => { - if (!_.startsWith(abiParam.type, 'tuple')) { - return abiParam.type; - } else { - // Need to expand tuples: - // E.g: fillOrder(tuple,uint256,bytes) -> fillOrder((address,address,address,address,uint256,uint256,uint256,uint256,uint256,uint256,bytes,bytes),uint256,bytes) - const isArray = _.endsWith(abiParam.type, '[]'); - const expandedTypes = _.map(abiParam.components, c => c.type); - const type = `(${expandedTypes.join(',')})${isArray ? '[]' : ''}`; - return 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[]): Type { - if (outputs.length > 1) { - const type: Type = { - name: '', - typeDocType: TypeDocTypes.Tuple, - tupleElements: [], - }; - for (const output of outputs) { - const tupleType = _getTypeFromDataItem(output); - (type.tupleElements as Type[]).push(tupleType); - } - return type; - } else if (outputs.length === 1) { - const output = outputs[0]; - const type = _getTypeFromDataItem(output); - return type; - } else { - const type: Type = { - name: 'void', - typeDocType: TypeDocTypes.Intrinsic, - }; - return type; - } -} - -function _capitalize(text: string): string { - return `${text.charAt(0).toUpperCase()}${text.slice(1)}`; -} - -function _dedupStructs(customTypes: CustomType[]): CustomType[] { - const uniqueCustomTypes: CustomType[] = []; - const seenTypes: { [hash: string]: boolean } = {}; - _.each(customTypes, customType => { - const hash = _generateCustomTypeHash(customType); - if (!seenTypes[hash]) { - uniqueCustomTypes.push(customType); - seenTypes[hash] = true; - } - }); - return uniqueCustomTypes; -} - -function _overwriteStructNames(customTypes: CustomType[]): CustomType[] { - const localCustomTypes = _.cloneDeep(customTypes); - _.each(localCustomTypes, customType => { - const hash = _generateCustomTypeHash(customType); - if (!_.isUndefined(customTypeHashToName[hash])) { - customType.name = customTypeHashToName[hash]; - } - }); - return localCustomTypes; -} - -function _generateCustomTypeHash(customType: CustomType): string { - const customTypeWithoutName = _.cloneDeep(customType); - delete customTypeWithoutName.name; - const customTypeWithoutNameStr = JSON.stringify(customTypeWithoutName); - const hash = ethUtil.sha256(customTypeWithoutNameStr).toString('hex'); - return hash; -} - -function _getStructsAsCustomTypes(abiDefinition: AbiDefinition): CustomType[] { - const customTypes: CustomType[] = []; - // We cast to `any` here because we do not know yet if this type of abiDefinition contains - // an `input` key - if (!_.isUndefined((abiDefinition as any).inputs)) { - const methodOrConstructorAbi = abiDefinition as MethodAbi | ConstructorAbi; - _.each(methodOrConstructorAbi.inputs, input => { - if (!_.isUndefined(input.components)) { - const customType = _getCustomTypeFromDataItem(input); - customTypes.push(customType); - } - }); - } - if (!_.isUndefined((abiDefinition as any).outputs)) { - const methodAbi = abiDefinition as MethodAbi; - _.each(methodAbi.outputs, output => { - if (!_.isUndefined(output.components)) { - const customType = _getCustomTypeFromDataItem(output); - customTypes.push(customType); - } - }); - } - return customTypes; -} - -function _getCustomTypeFromDataItem(inputOrOutput: DataItem): CustomType { - const customType: CustomType = { - name: _.capitalize(inputOrOutput.name), - kindString: 'Interface', - children: [], - }; - _.each(inputOrOutput.components, (component: DataItem) => { - const childType = _getTypeFromDataItem(component); - const customTypeChild = { - name: component.name, - type: childType, - }; - // (fabio): Not sure why this type casting is necessary. Seems TS doesn't - // deduce that `customType.children` cannot be undefined anymore after being - // set to `[]` above. - (customType.children as CustomTypeChild[]).push(customTypeChild); - }); - return customType; -} - -function _getNameFromDataItemIfExists(dataItem: DataItem): string | undefined { - if (_.isUndefined(dataItem.components)) { - return undefined; - } - const customType = _getCustomTypeFromDataItem(dataItem); - const hash = _generateCustomTypeHash(customType); - if (_.isUndefined(customTypeHashToName[hash])) { - return undefined; - } - return customTypeHashToName[hash]; -} - -function _getTypeFromDataItem(dataItem: DataItem): Type { - const typeDocType = !_.isUndefined(dataItem.components) ? TypeDocTypes.Reference : TypeDocTypes.Intrinsic; - let typeName: string; - if (typeDocType === TypeDocTypes.Reference) { - const nameIfExists = _getNameFromDataItemIfExists(dataItem); - typeName = _.isUndefined(nameIfExists) ? _capitalize(dataItem.name) : nameIfExists; - } else { - typeName = dataItem.type; - } - - const isArrayType = _.endsWith(dataItem.type, '[]'); - let type: Type; - if (isArrayType) { - // tslint:disable-next-line:custom-no-magic-numbers - typeName = typeDocType === TypeDocTypes.Intrinsic ? typeName.slice(0, -2) : typeName; - type = { - elementType: { name: typeName, typeDocType }, - typeDocType: TypeDocTypes.Array, - name: '', - }; - } else { - type = { name: typeName, typeDocType }; - } - return type; -} -// tslint:disable:max-file-line-count diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts index c780d3d31..ba08ebd00 100644 --- a/packages/sol-doc/test/solidity_doc_generator_test.ts +++ b/packages/sol-doc/test/solidity_doc_generator_test.ts @@ -5,16 +5,20 @@ import 'mocha'; import { DocAgnosticFormat, Event, SolidityMethod } from '@0xproject/types'; -import { generateSolDocAsync } from '../src/solidity_doc_generator'; +import { SolDoc } from '../src/sol_doc'; import { chaiSetup } from './util/chai_setup'; chaiSetup.configure(); const expect = chai.expect; +let solDoc: SolDoc; describe('#SolidityDocGenerator', () => { + before(() => { + solDoc = new SolDoc(); + }); it('should generate a doc object that matches the devdoc-free TokenTransferProxy fixture', async () => { - const doc = await generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [ + const doc = await solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [ 'TokenTransferProxyNoDevdoc', ]); expect(doc).to.not.be.undefined(); @@ -22,8 +26,8 @@ describe('#SolidityDocGenerator', () => { verifyTokenTransferProxyABIIsDocumented(doc, 'TokenTransferProxyNoDevdoc'); }); const docPromises: Array> = [ - generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`), - generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, []), + solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`), + solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, []), ]; docPromises.forEach(docPromise => { it('should generate a doc object that matches the TokenTransferProxy fixture with its dependencies', async () => { @@ -48,7 +52,7 @@ describe('#SolidityDocGenerator', () => { }); }); it('should generate a doc object that matches the TokenTransferProxy fixture', async () => { - const doc: DocAgnosticFormat = await generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [ + const doc: DocAgnosticFormat = await solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [ 'TokenTransferProxy', ]); verifyTokenTransferProxyABIIsDocumented(doc, 'TokenTransferProxy'); @@ -56,7 +60,7 @@ describe('#SolidityDocGenerator', () => { 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']); + doc = await solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, ['NatspecEverything']); expect(doc).to.not.be.undefined(); expect(doc.NatspecEverything).to.not.be.undefined(); }); @@ -159,7 +163,9 @@ describe('#SolidityDocGenerator', () => { }); }); it('should document a method that returns multiple values', async () => { - const doc = await generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, ['MultipleReturnValues']); + const doc = await solDoc.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; -- cgit v1.2.3 From 033340e304a92e4022cd3bce06f612e904a73faf Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Fri, 28 Sep 2018 18:38:10 +0100 Subject: Fix typo --- packages/sol-doc/src/cli.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packages/sol-doc/src/cli.ts b/packages/sol-doc/src/cli.ts index 04956510e..11e638785 100644 --- a/packages/sol-doc/src/cli.ts +++ b/packages/sol-doc/src/cli.ts @@ -20,14 +20,14 @@ const JSON_TAB_WIDTH = 4; .demandOption('contracts-dir') .array('contracts') .help().argv; - // Unforunately, the only way to currently retrieve the declared structs within Solidity contracts + // Unfortunately, the only way to currently retrieve the declared structs within Solidity contracts // is to tease them out of the params/return values included in the ABI. These structures do // not include the structs actual name, so we need a mapping to assign the proper name to a // struct. If the name is not in this mapping, the structs name will default to the param/return value // name (which mostly coincide). const customTypeHashToName: { [hash: string]: string } = { '52d4a768701076c7bac06e386e430883975eb398732eccba797fd09dd064a60e': 'Order', - '46f7e8c4d144d11a72ce5338458ea37b933500d7a65e740cbca6d16e350eaa48': 'FillResult', + '46f7e8c4d144d11a72ce5338458ea37b933500d7a65e740cbca6d16e350eaa48': 'FillResults', c22239cf0d29df1e6cf1be54f21692a8c0b3a48b9367540d4ffff4608b331ce9: 'OrderInfo', c21e9ff31a30941c22e1cb43752114bb467c34dea58947f98966c9030fc8e4a9: 'TraderInfo', '07c2bddc165e0b5005e6244dd4a9771fa61c78c4f42abd687d57567b0768136c': 'MatchedFillResults', -- cgit v1.2.3 From 005b7a55e866a735e86dc58ff62b0cf3301f59cd Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Sat, 29 Sep 2018 14:22:05 +0100 Subject: Fix tests --- packages/sol-doc/test/solidity_doc_generator_test.ts | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts index ba08ebd00..91e0af789 100644 --- a/packages/sol-doc/test/solidity_doc_generator_test.ts +++ b/packages/sol-doc/test/solidity_doc_generator_test.ts @@ -11,12 +11,9 @@ import { chaiSetup } from './util/chai_setup'; chaiSetup.configure(); const expect = chai.expect; -let solDoc: SolDoc; +const solDoc = new SolDoc(); describe('#SolidityDocGenerator', () => { - before(() => { - solDoc = new SolDoc(); - }); it('should generate a doc object that matches the devdoc-free TokenTransferProxy fixture', async () => { const doc = await solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [ 'TokenTransferProxyNoDevdoc', -- cgit v1.2.3 From 2b6a9911f5f821114a65474e75f5ed52e8bad980 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Sat, 29 Sep 2018 14:22:33 +0100 Subject: Add test for methodSignature gen for methods with param/return structs --- .../fixtures/contracts/StructParamAndReturn.sol | 18 +++++++++++++++ .../sol-doc/test/solidity_doc_generator_test.ts | 26 ++++++++++++++++++++++ 2 files changed, 44 insertions(+) create mode 100644 packages/sol-doc/test/fixtures/contracts/StructParamAndReturn.sol diff --git a/packages/sol-doc/test/fixtures/contracts/StructParamAndReturn.sol b/packages/sol-doc/test/fixtures/contracts/StructParamAndReturn.sol new file mode 100644 index 000000000..b9a7ccdbc --- /dev/null +++ b/packages/sol-doc/test/fixtures/contracts/StructParamAndReturn.sol @@ -0,0 +1,18 @@ +pragma solidity 0.4.24; +pragma experimental ABIEncoderV2; + + +contract StructParamAndReturn { + + struct Stuff { + address anAddress; + uint256 aNumber; + } + + /// @dev DEV_COMMENT + /// @param stuff STUFF_COMMENT + /// @return RETURN_COMMENT + function methodWithStructParamAndReturn(Stuff stuff) public pure returns(Stuff) { + return stuff; + } +} diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts index 91e0af789..081fd4188 100644 --- a/packages/sol-doc/test/solidity_doc_generator_test.ts +++ b/packages/sol-doc/test/solidity_doc_generator_test.ts @@ -181,6 +181,32 @@ describe('#SolidityDocGenerator', () => { } expect(returnType.tupleElements.length).to.equal(2); }); + it('should document a method that has a struct param and return value', async () => { + const doc = await solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [ + 'StructParamAndReturn', + ]); + expect(doc.StructParamAndReturn).to.not.be.undefined(); + expect(doc.StructParamAndReturn.methods).to.not.be.undefined(); + let methodWithStructParamAndReturn: SolidityMethod | undefined; + for (const method of doc.StructParamAndReturn.methods) { + if (method.name === 'methodWithStructParamAndReturn') { + methodWithStructParamAndReturn = method; + } + } + if (_.isUndefined(methodWithStructParamAndReturn)) { + throw new Error('method should not be undefined'); + } + /** + * Solc maps devDoc comments to methods using a method signature. If we incorrectly + * generate the methodSignatures, the devDoc comments won't be correctly associated + * with their methods and they won't show up in the output. By checking that the comments + * are included for a method with structs as params/returns, we are sure that the methodSignature + * generation is correct for this case. + */ + expect(methodWithStructParamAndReturn.comment).to.be.equal('DEV_COMMENT'); + expect(methodWithStructParamAndReturn.returnComment).to.be.equal('RETURN_COMMENT'); + expect(methodWithStructParamAndReturn.parameters[0].comment).to.be.equal('STUFF_COMMENT'); + }); }); function verifyTokenTransferProxyABIIsDocumented(doc: DocAgnosticFormat, contractName: string): void { -- cgit v1.2.3 From b9eb2b3918b4b1a891c07a4ccb5eb40847ae90fc Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Sat, 29 Sep 2018 14:22:49 +0100 Subject: Add test that structs are documented in separate section --- packages/sol-doc/test/solidity_doc_generator_test.ts | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts index 081fd4188..f166fb143 100644 --- a/packages/sol-doc/test/solidity_doc_generator_test.ts +++ b/packages/sol-doc/test/solidity_doc_generator_test.ts @@ -207,6 +207,13 @@ describe('#SolidityDocGenerator', () => { expect(methodWithStructParamAndReturn.returnComment).to.be.equal('RETURN_COMMENT'); expect(methodWithStructParamAndReturn.parameters[0].comment).to.be.equal('STUFF_COMMENT'); }); + it('should document the structs included in a contract', async () => { + const doc = await solDoc.generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, [ + 'StructParamAndReturn', + ]); + expect(doc.structs).to.not.be.undefined(); + expect(doc.structs.types.length).to.be.equal(1); + }); }); function verifyTokenTransferProxyABIIsDocumented(doc: DocAgnosticFormat, contractName: string): void { -- cgit v1.2.3 From 6ffdc318e7b15cc43f4b3e0ffc39786cdf4c5c05 Mon Sep 17 00:00:00 2001 From: Fabio Berger Date: Mon, 1 Oct 2018 16:10:22 +0100 Subject: Disable max file line count tslint rule for types file --- packages/ethereum-types/src/index.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/ethereum-types/src/index.ts b/packages/ethereum-types/src/index.ts index 916661638..2f3140a58 100644 --- a/packages/ethereum-types/src/index.ts +++ b/packages/ethereum-types/src/index.ts @@ -497,4 +497,4 @@ export interface CompilerOptions { compilerSettings?: CompilerSettings; contracts?: string[] | '*'; solcVersion?: string; -} +} // tslint:disable:max-file-line-count -- cgit v1.2.3