feat: Config option to exclude not explicitly documented symbols (#996)

Closes #995
TypeStrong · Feb 28, 2020 · 20db9a5 · 20db9a5
1 parent 541fbcf
commit 20db9a5
Show file tree

Hide file tree

Showing 7 changed files with 4,595 additions and 1 deletion.
diff --git a/scripts/rebuild_specs.js b/scripts/rebuild_specs.js
@@ -42,6 +42,10 @@ const conversions = [
         () => app.options.setValue('categorizeByGroup', false),
         () => app.options.setValue('categorizeByGroup', true)
     ],
+    ['specs.nodoc',
+        () => app.options.setValue('excludeNotDocumented', true),
+        () => app.options.setValue('excludeNotDocumented', false)
+    ]
 ];
 
 /**

diff --git a/src/lib/converter/converter.ts b/src/lib/converter/converter.ts
@@ -49,6 +49,9 @@ export class Converter extends ChildableComponent<Application, ConverterComponen
     @BindOption('excludeNotExported')
     excludeNotExported!: boolean;
 
+    @BindOption('excludeNotDocumented')
+    excludeNotDocumented!: boolean;
+
     @BindOption('excludePrivate')
     excludePrivate!: boolean;
 

diff --git a/src/lib/converter/factories/declaration.ts b/src/lib/converter/factories/declaration.ts
@@ -3,6 +3,7 @@ import * as ts from 'typescript';
 import { ContainerReflection, DeclarationReflection, ReflectionFlag, ReflectionKind } from '../../models/index';
 import { Context } from '../context';
 import { Converter } from '../converter';
+import { getRawComment } from './comment.js';
 import { createReferenceType } from './reference';
 
 /**
@@ -69,10 +70,12 @@ export function createDeclaration(context: Context, node: ts.Declaration, kind:
 
     const modifiers = ts.getCombinedModifierFlags(node);
 
+    let hasComment: boolean = Boolean(getRawComment(node));
     // Test whether the node is exported
     let isExported: boolean;
     if (kind === ReflectionKind.ExternalModule || kind === ReflectionKind.Global) {
         isExported = true;
+        hasComment = true;
     } else if (container.kind === ReflectionKind.Global) {
         // In file mode, everything is exported.
         isExported = true;
@@ -98,7 +101,11 @@ export function createDeclaration(context: Context, node: ts.Declaration, kind:
         isExported = container.flags.isExported;
     }
 
-    if (!isExported && context.converter.excludeNotExported) {
+    if (
+        (!isExported && context.converter.excludeNotExported)
+        ||
+        (context.converter.excludeNotDocumented && kind !== ReflectionKind.EnumMember && !hasComment)
+    ) {
         return;
     }
 

diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts
@@ -61,6 +61,11 @@ export function addTypeDocOptions(options: Options) {
         help: 'Prevent symbols that are not exported from being documented.',
         type: ParameterType.Boolean
     });
+    options.addDeclaration({
+        name: 'excludeNotDocumented',
+        help: 'Prevent symbols that are not explicitly documented from appearing in the results.',
+        type: ParameterType.Boolean
+    });
     options.addDeclaration({
         name: 'excludePrivate',
         help: 'Ignores private variables and methods',

diff --git a/src/test/converter.test.ts b/src/test/converter.test.ts
@@ -79,3 +79,39 @@ describe('Serializer', () => {
         equal(json, typed);
     });
 });
+
+// describe('Converter with excludeNotDocumented=true', function() {
+//     const base = Path.join(__dirname, 'converter');
+//     const fixtureDir = Path.join(base, 'exclude-not-documented');
+//     let app: Application;
+//
+//     before('constructs', function() {
+//         app = new Application({
+//             mode:   'Modules',
+//             logger: 'none',
+//             target: 'ES5',
+//             module: 'CommonJS',
+//             experimentalDecorators: true,
+//             excludeNotDocumented: true,
+//             jsx: 'react'
+//         });
+//     });
+//
+//     let result: ProjectReflection | undefined;
+//
+//     describe('Exclude not documented symbols', () => {
+//         it('converts fixtures', function() {
+//             resetReflectionID();
+//             result = app.convert(app.expandInputFiles([fixtureDir]));
+//             Assert(result instanceof ProjectReflection, 'No reflection returned');
+//         });
+//
+//         it('matches specs', function() {
+//             const specs = JSON.parse(FS.readFileSync(Path.join(fixtureDir, 'specs-without-undocumented.json')).toString());
+//             let data = JSON.stringify(result!.toObject(), null, '  ');
+//             data = data.split(normalizePath(base)).join('%BASE%');
+//
+//             compareReflections(JSON.parse(data), specs);
+//         });
+//     });
+// });