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