Add excludeNotDocumentedKinds option

Resolves #2162

Author: Gerrit0

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Unreleased
 
+### Breaking Changes
+
+-   Upgraded Shiki, if your highlight theme was set to `material-<theme>`, the value will need to be changed to
+    `material-theme-<theme>`, see the [Shiki release notes](https://github.com/shikijs/shiki/blob/main/CHANGELOG.md#0130--2023-01-27).
+
+### Features
+
+-   Added new `excludeNotDocumentedKinds` variable to control which reflection types can be removed
+    by the `excludeNotDocumented` option, #2162.
+-   Added `typedoc.jsonc`, `typedoc.config.js`, `typedoc.config.cjs`, `typedoc.cjs` to the list of files
+    which TypeDoc will automatically use as configuration files.
+
+### Bug Fixes
+
+-   Entry points under `node_modules` will no longer be ignored, #2151.
+
+### Thanks!
+
+-   @boneskull
+-   @Mikkal24
+-   @zamiell
+
 ## v0.23.24 (2023-01-07)
 
 ### Bug Fixes

src/lib/converter/plugins/CommentPlugin.ts

@@ -118,6 +118,14 @@ export class CommentPlugin extends ConverterComponent {
     @BindOption("excludeNotDocumented")
     excludeNotDocumented!: boolean;
 
+    private _excludeKinds: number | undefined;
+    private get excludeNotDocumentedKinds(): number {
+        this._excludeKinds ??= this.application.options
+            .getValue("excludeNotDocumentedKinds")
+            .reduce((a, b) => a | ReflectionKind[b], 0);
+        return this._excludeKinds;
+    }
+
     /**
      * Create a new CommentPlugin instance.
      */
@@ -128,6 +136,9 @@ export class CommentPlugin extends ConverterComponent {
             [Converter.EVENT_CREATE_TYPE_PARAMETER]: this.onCreateTypeParameter,
             [Converter.EVENT_RESOLVE_BEGIN]: this.onBeginResolve,
             [Converter.EVENT_RESOLVE]: this.onResolve,
+            [Converter.EVENT_END]: () => {
+                this._excludeKinds = undefined;
+            },
         });
     }
 
@@ -462,6 +473,10 @@ export class CommentPlugin extends ConverterComponent {
                     return false;
                 }
 
+                if (!reflection.kindOf(this.excludeNotDocumentedKinds)) {
+                    return false;
+                }
+
                 // excludeNotDocumented should hide a module only if it has no visible children
                 if (reflection.kindOf(ReflectionKind.SomeModule)) {
                     if (!(reflection as DeclarationReflection).children) {
@@ -472,11 +487,6 @@ export class CommentPlugin extends ConverterComponent {
                     ).children!.every((child) => this.isHidden(child));
                 }
 
-                // enum members should all be included if the parent enum is documented
-                if (reflection.kind === ReflectionKind.EnumMember) {
-                    return false;
-                }
-
                 // signature containers should only be hidden if all their signatures are hidden
                 if (reflection.kindOf(ReflectionKind.SignatureContainer)) {
                     return (reflection as DeclarationReflection)

src/lib/utils/options/declaration.ts

@@ -85,6 +85,7 @@ export interface TypeDocOptionMap {
     externalPattern: string[];
     excludeExternals: boolean;
     excludeNotDocumented: boolean;
+    excludeNotDocumentedKinds: Array<keyof typeof ReflectionKind>;
     excludeInternal: boolean;
     excludePrivate: boolean;
     excludeProtected: boolean;

src/lib/utils/options/sources/typedoc.ts

@@ -85,6 +85,58 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         help: "Prevent symbols that are not explicitly documented from appearing in the results.",
         type: ParameterType.Boolean,
     });
+    options.addDeclaration({
+        name: "excludeNotDocumentedKinds",
+        help: "Specify the type of reflections that can be removed by excludeNotDocumented.",
+        type: ParameterType.Array,
+        validate(value) {
+            const invalid = new Set(value);
+            const valid = new Set(getEnumKeys(ReflectionKind));
+            for (const notPermitted of [
+                ReflectionKind.Project,
+                ReflectionKind.TypeLiteral,
+                ReflectionKind.TypeParameter,
+                ReflectionKind.Parameter,
+                ReflectionKind.ObjectLiteral,
+            ]) {
+                valid.delete(ReflectionKind[notPermitted]);
+            }
+            for (const v of valid) {
+                invalid.delete(v);
+            }
+
+            if (invalid.size !== 0) {
+                throw new Error(
+                    `excludeNotDocumentedKinds may only specify known values, and invalid values were provided (${Array.from(
+                        invalid
+                    ).join(", ")}). The valid kinds are:\n${Array.from(
+                        valid
+                    ).join(", ")}`
+                );
+            }
+        },
+        defaultValue: [
+            ReflectionKind[ReflectionKind.Module],
+            ReflectionKind[ReflectionKind.Namespace],
+            ReflectionKind[ReflectionKind.Enum],
+            // Not including enum member here by default
+            ReflectionKind[ReflectionKind.Variable],
+            ReflectionKind[ReflectionKind.Function],
+            ReflectionKind[ReflectionKind.Class],
+            ReflectionKind[ReflectionKind.Interface],
+            ReflectionKind[ReflectionKind.Constructor],
+            ReflectionKind[ReflectionKind.Property],
+            ReflectionKind[ReflectionKind.Method],
+            ReflectionKind[ReflectionKind.CallSignature],
+            ReflectionKind[ReflectionKind.IndexSignature],
+            ReflectionKind[ReflectionKind.ConstructorSignature],
+            ReflectionKind[ReflectionKind.Accessor],
+            ReflectionKind[ReflectionKind.GetSignature],
+            ReflectionKind[ReflectionKind.SetSignature],
+            ReflectionKind[ReflectionKind.TypeAlias],
+            ReflectionKind[ReflectionKind.Reference],
+        ],
+    });
     options.addDeclaration({
         name: "excludeInternal",
         help: "Prevent symbols that are marked with @internal from being documented.",
@@ -631,16 +683,16 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
             }
         },
         defaultValue: [
-            "Enum",
-            "EnumMember",
-            "Variable",
-            "Function",
-            "Class",
-            "Interface",
-            "Property",
-            "Method",
-            "Accessor",
-            "TypeAlias",
+            ReflectionKind[ReflectionKind.Enum],
+            ReflectionKind[ReflectionKind.EnumMember],
+            ReflectionKind[ReflectionKind.Variable],
+            ReflectionKind[ReflectionKind.Function],
+            ReflectionKind[ReflectionKind.Class],
+            ReflectionKind[ReflectionKind.Interface],
+            ReflectionKind[ReflectionKind.Property],
+            ReflectionKind[ReflectionKind.Method],
+            ReflectionKind[ReflectionKind.Accessor],
+            ReflectionKind[ReflectionKind.TypeAlias],
         ],
     });
 

src/test/behaviorTests.ts

@@ -10,6 +10,7 @@ import {
     CommentTag,
     Reflection,
     SignatureReflection,
+    ContainerReflection,
 } from "../lib/models";
 import { Chars, filterMap } from "../lib/utils";
 import { CommentStyle } from "../lib/utils/options/declaration";
@@ -21,6 +22,20 @@ function query(project: ProjectReflection, name: string) {
     return reflection;
 }
 
+type NameTree = { [name: string]: NameTree };
+
+function buildNameTree(
+    refl: ContainerReflection,
+    tree: NameTree = {}
+): NameTree {
+    for (const child of refl.children || []) {
+        tree[child.name] ||= {};
+        buildNameTree(child, tree[child.name]);
+    }
+
+    return tree;
+}
+
 type Letters = Chars<"abcdefghijklmnopqrstuvwxyz">;
 
 export const behaviorTests: {
@@ -201,6 +216,19 @@ export const behaviorTests: {
         logger.expectNoOtherMessages();
     },
 
+    _excludeNotDocumentedKinds(app) {
+        app.options.setValue("excludeNotDocumented", true);
+        app.options.setValue("excludeNotDocumentedKinds", ["Property"]);
+    },
+    excludeNotDocumentedKinds(project) {
+        equal(buildNameTree(project), {
+            NotDoc: {
+                prop: {},
+            },
+            identity: {},
+        });
+    },
+
     exportComments(project) {
         const abc = query(project, "abc");
         equal(abc.kind, ReflectionKind.Variable);

src/test/converter2/behavior/excludeNotDocumentedKinds.ts

@@ -0,0 +1,11 @@
+export interface NotDoc {
+    /** Doc */
+    prop: 123;
+
+    notDoc: 456;
+}
+
+/** Doc */
+export function identity<T>(x: T): T {
+    return x;
+}