aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorF. Eugene Aumson <gene@aumson.org>2018-09-01 03:34:13 +0800
committerF. Eugene Aumson <gene@aumson.org>2018-09-01 04:18:17 +0800
commit800dd5fb4f0ab21388440a46aef21cd0cf0801c3 (patch)
tree62f1c706aa3a35ab28d60c157630997ae624d152
parent3dc4eb4421d4f0b1294fcaaa4602245005f36e82 (diff)
downloaddexon-0x-contracts-800dd5fb4f0ab21388440a46aef21cd0cf0801c3.tar
dexon-0x-contracts-800dd5fb4f0ab21388440a46aef21cd0cf0801c3.tar.gz
dexon-0x-contracts-800dd5fb4f0ab21388440a46aef21cd0cf0801c3.tar.bz2
dexon-0x-contracts-800dd5fb4f0ab21388440a46aef21cd0cf0801c3.tar.lz
dexon-0x-contracts-800dd5fb4f0ab21388440a46aef21cd0cf0801c3.tar.xz
dexon-0x-contracts-800dd5fb4f0ab21388440a46aef21cd0cf0801c3.tar.zst
dexon-0x-contracts-800dd5fb4f0ab21388440a46aef21cd0cf0801c3.zip
ammend generated docs with solc's devdoc output
-rw-r--r--packages/sol-doc/src/solidity_doc_generator.ts61
-rw-r--r--packages/sol-doc/test/solidity_doc_generator_test.ts17
2 files changed, 63 insertions, 15 deletions
diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts
index 240fbbd75..a1ef32e79 100644
--- a/packages/sol-doc/src/solidity_doc_generator.ts
+++ b/packages/sol-doc/src/solidity_doc_generator.ts
@@ -117,10 +117,8 @@ function _genConstructorDoc(abiDefinition: ConstructorAbi, devdocIfExists: Devdo
devdocIfExists,
);
- let comment;
- // TODO: use methodSignature as the key to abiEntry.devdoc.methods, and
- // from that object extract the "details" (comment) property
- comment = `something from devdoc, using ${methodSignature} to find it`;
+ const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
+ // TODO: figure out why devdoc'd constructors don't get output by solc
const constructorDoc: SolidityMethod = {
isConstructor: true,
@@ -136,6 +134,26 @@ function _genConstructorDoc(abiDefinition: ConstructorAbi, devdocIfExists: Devdo
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,
@@ -147,10 +165,7 @@ function _genMethodDoc(
? { parameters: [], methodSignature: `${name}()` }
: _genMethodParamsDoc(name, abiDefinition.inputs, devdocIfExists);
- let comment;
- // TODO: use methodSignature as the key to abiEntry.devdoc.methods, and
- // from that object extract the "details" (comment) property
- comment = 'something from devdoc';
+ const comment = _devdocMethodDetailsIfExist(methodSignature, devdocIfExists);
const returnType =
abiDefinition.type === 'fallback'
@@ -205,9 +220,6 @@ function _genEventArgsDoc(args: DataItem[], devdocIfExists: DevdocOutput | undef
/**
* Extract documentation for each method paramater from @param params.
- * TODO: Then, use @param name, along with the types of the method
- * parameters, to form a method signature. That signature is the key to
- * the method documentation held in @param devdocIfExists.
*/
function _genMethodParamsDoc(
name: string,
@@ -215,18 +227,37 @@ function _genMethodParamsDoc(
devdocIfExists: DevdocOutput | undefined,
): { parameters: Parameter[]; methodSignature: string } {
const parameters: Parameter[] = [];
+ let methodSignature = `${name}(`;
+
for (const abiParam of abiParams) {
const parameter: Parameter = {
name: abiParam.name,
- comment: '', // TODO: get from devdoc. see comment below.
+ 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);
+ methodSignature = `${methodSignature}${abiParam.type},`;
}
- // TODO: use methodSignature as the key to abiEntry.devdoc.methods, and
- // from that object extract the "details" (comment) property
- return { parameters, methodSignature: '' };
+
+ if (methodSignature.slice(-1) === ',') {
+ methodSignature = methodSignature.slice(0, -1);
+ }
+ methodSignature += ')';
+
+ 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(
diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts
index 989f29320..7f11fcdfd 100644
--- a/packages/sol-doc/test/solidity_doc_generator_test.ts
+++ b/packages/sol-doc/test/solidity_doc_generator_test.ts
@@ -3,6 +3,8 @@ import * as _ from 'lodash';
import * as chai from 'chai';
import 'mocha';
+import { SolidityMethod } from '@0xproject/types';
+
import { generateSolDocAsync } from '../src/solidity_doc_generator';
import { chaiSetup } from './util/chai_setup';
@@ -55,5 +57,20 @@ describe('#SolidityDocGenerator', () => {
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.TokenTransferProxy.methods) {
+ if (method.name === 'addAuthorizedAddress') {
+ addAuthorizedAddressMethod = method;
+ }
+ }
+ expect(
+ addAuthorizedAddressMethod,
+ `method addAuthorizedAddress not found in ${JSON.stringify(doc.TokenTransferProxy.methods)}`,
+ ).to.not.be.undefined();
+ const tokenTransferProxyAddAuthorizedAddressComment = 'Authorizes an address.';
+ expect((addAuthorizedAddressMethod as SolidityMethod).comment).to.equal(
+ tokenTransferProxyAddAuthorizedAddressComment,
+ );
});
});