From 9f0dfb1e1a4c97e462cf298e0452be1d0fcf2216 Mon Sep 17 00:00:00 2001
From: "F. Eugene Aumson" <gene@aumson.org>
Date: Sat, 22 Sep 2018 10:31:47 -0400
Subject: feat: make sol-doc only document what's requested

if a list of contracts-to-document is passed into sol-doc, then the
output should only contain documentation for the contracts requested.

if an empty/undefined list is passed, then it should document all
contracts that were found.
---
 packages/sol-doc/src/solidity_doc_generator.ts     | 21 ++++++++++++++---
 .../sol-doc/test/solidity_doc_generator_test.ts    | 26 +++++++++-------------
 2 files changed, 29 insertions(+), 18 deletions(-)

(limited to 'packages')

diff --git a/packages/sol-doc/src/solidity_doc_generator.ts b/packages/sol-doc/src/solidity_doc_generator.ts
index 2586cf91c..074fb1f37 100644
--- a/packages/sol-doc/src/solidity_doc_generator.ts
+++ b/packages/sol-doc/src/solidity_doc_generator.ts
@@ -1,3 +1,5 @@
+import * as path from 'path';
+
 import * as _ from 'lodash';
 
 import {
@@ -34,8 +36,7 @@ export async function generateSolDocAsync(
     contractsDir: string,
     contractsToDocument?: string[],
 ): Promise<DocAgnosticFormat> {
-    const doc: DocAgnosticFormat = {};
-
+    const docWithDependencies: DocAgnosticFormat = {};
     const compilerOptions = _makeCompilerOptions(contractsDir, contractsToDocument);
     const compiler = new Compiler(compilerOptions);
     const compilerOutputs = await compiler.getCompilerOutputsAsync();
@@ -50,11 +51,25 @@ export async function generateSolDocAsync(
                 if (_.isUndefined(compiledContract.abi)) {
                     throw new Error('compiled contract did not contain ABI output');
                 }
-                doc[contractName] = _genDocSection(compiledContract);
+                docWithDependencies[contractName] = _genDocSection(compiledContract);
             }
         }
     }
 
+    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;
 }
 
diff --git a/packages/sol-doc/test/solidity_doc_generator_test.ts b/packages/sol-doc/test/solidity_doc_generator_test.ts
index 5004b1a90..0cbb786af 100644
--- a/packages/sol-doc/test/solidity_doc_generator_test.ts
+++ b/packages/sol-doc/test/solidity_doc_generator_test.ts
@@ -24,14 +24,13 @@ describe('#SolidityDocGenerator', () => {
     const docPromises: Array<Promise<DocAgnosticFormat>> = [
         generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`),
         generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, []),
-        generateSolDocAsync(`${__dirname}/../../test/fixtures/contracts`, ['TokenTransferProxy']),
     ];
     docPromises.forEach(docPromise => {
-        it('should generate a doc object that matches the TokenTransferProxy fixture', async () => {
+        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();
 
-            verifyTokenTransferProxyABIIsDocumented(doc, 'TokenTransferProxy');
+            verifyTokenTransferProxyAndDepsABIsAreDocumented(doc, 'TokenTransferProxy');
 
             let addAuthorizedAddressMethod: SolidityMethod | undefined;
             for (const method of doc.TokenTransferProxy.methods) {
@@ -48,6 +47,12 @@ describe('#SolidityDocGenerator', () => {
             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 () => {
@@ -188,19 +193,10 @@ function verifyTokenTransferProxyABIIsDocumented(doc: DocAgnosticFormat, contrac
         throw new Error('events should never be undefined');
     }
     expect(events.length).to.equal(tokenTransferProxyEventCount);
+}
 
-    expect(doc.Ownable).to.not.be.undefined();
-    expect(doc.Ownable.constructors).to.not.be.undefined();
-    expect(doc.Ownable.methods).to.not.be.undefined();
-    const ownableConstructorCount = 1;
-    const ownableMethodCount = 2;
-    const ownableEventCount = 1;
-    expect(doc.Ownable.constructors.length).to.equal(ownableConstructorCount);
-    expect(doc.Ownable.methods.length).to.equal(ownableMethodCount);
-    if (_.isUndefined(doc.Ownable.events)) {
-        throw new Error('events should never be undefined');
-    }
-    expect(doc.Ownable.events.length).to.equal(ownableEventCount);
+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();
-- 
cgit v1.2.3