aboutsummaryrefslogtreecommitdiffstats
path: root/packages/sol-doc
diff options
context:
space:
mode:
Diffstat (limited to 'packages/sol-doc')
-rw-r--r--packages/sol-doc/test/fixtures/contracts/NatspecEverything.sol37
-rw-r--r--packages/sol-doc/test/solidity_doc_generator_test.ts104
2 files changed, 140 insertions, 1 deletions
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..3dea03c9a
--- /dev/null
+++ b/packages/sol-doc/test/fixtures/contracts/NatspecEverything.sol
@@ -0,0 +1,37 @@
+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; }
+
+ /// @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/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts
index 47289c7c6..bae67001b 100644
--- a/packages/sol-doc/test/solidity_doc_generator_test.ts
+++ b/packages/sol-doc/test/solidity_doc_generator_test.ts
@@ -3,7 +3,7 @@ import * as _ from 'lodash';
import * as chai from 'chai';
import 'mocha';
-import { DocAgnosticFormat, SolidityMethod } from '@0xproject/types';
+import { DocAgnosticFormat, Event, SolidityMethod } from '@0xproject/types';
import { generateSolDocAsync } from '../src/solidity_doc_generator';
@@ -43,6 +43,108 @@ describe('#SolidityDocGenerator', () => {
expect((addAuthorizedAddressMethod as SolidityMethod).comment).to.equal(
tokenTransferProxyAddAuthorizedAddressComment,
);
+
+ const expectedParamComment = 'Address to authorize.';
+ expect((addAuthorizedAddressMethod as SolidityMethod).parameters[0].comment).to.equal(expectedParamComment);
+ });
+ });
+ 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 name', () => {
+ expect(methodDoc.returnType.name).to.equal('r');
+ });
+ });
+ 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 name', () => {
+ expect(methodDoc.returnType.name).to.equal('r');
+ });
+ });
+ 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');
});
});
});