feat: Support for excludeInternal

Resolves #1469
TypeStrong · Jan 16, 2021 · 4f4d85c · 4f4d85c
1 parent c01883b
commit 4f4d85c
Show file tree

Hide file tree

Showing 11 changed files with 90 additions and 12 deletions.
diff --git a/src/lib/converter/plugins/CommentPlugin.ts b/src/lib/converter/plugins/CommentPlugin.ts
@@ -259,8 +259,9 @@ export class CommentPlugin extends ConverterComponent {
             info.reflection.comment = comment;
         }
 
-        const stripInternal = !!this.application.options.getCompilerOptions()
-            .stripInternal;
+        const excludeInternal = this.application.options.getValue(
+            "excludeInternal"
+        );
         const excludePrivate = this.application.options.getValue(
             "excludePrivate"
         );
@@ -275,7 +276,7 @@ export class CommentPlugin extends ConverterComponent {
         const hidden = reflections.filter((reflection) =>
             CommentPlugin.isHidden(
                 reflection,
-                stripInternal,
+                excludeInternal,
                 excludePrivate,
                 excludeProtected
             )
@@ -387,7 +388,7 @@ export class CommentPlugin extends ConverterComponent {
      */
     private static isHidden(
         reflection: Reflection,
-        stripInternal: boolean,
+        excludeInternal: boolean,
         excludePrivate: boolean,
         excludeProtected: boolean
     ) {
@@ -414,7 +415,7 @@ export class CommentPlugin extends ConverterComponent {
         return (
             comment.hasTag("hidden") ||
             comment.hasTag("ignore") ||
-            (comment.hasTag("internal") && stripInternal)
+            (comment.hasTag("internal") && excludeInternal)
         );
     }
 }
diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts
@@ -43,6 +43,7 @@ export interface TypeDocOptionMap {
     excludePrivate: boolean;
     excludeProtected: boolean;
     excludeNotDocumented: boolean;
+    excludeInternal: boolean;
     disableSources: boolean;
     includes: string;
     media: string;

diff --git a/src/lib/utils/options/options.ts b/src/lib/utils/options/options.ts
@@ -78,6 +78,7 @@ export class Options {
     private _readers: OptionsReader[] = [];
     private _declarations = new Map<string, Readonly<DeclarationOption>>();
     private _values: Record<string, unknown> = {};
+    private _setOptions = new Set<string>();
     private _compilerOptions: ts.CompilerOptions = {};
     private _fileNames: readonly string[] = [];
     private _projectReferences: readonly ts.ProjectReference[] = [];
@@ -109,6 +110,7 @@ export class Options {
         for (const declaration of this.getDeclarations()) {
             this.setOptionValueToDefault(declaration);
         }
+        this._setOptions.clear();
         this._compilerOptions = {};
         this._fileNames = [];
     }
@@ -211,6 +213,7 @@ export class Options {
 
     /**
      * Checks if the given option's value is deeply strict equal to the default.
+     * @deprecated Will be removed in v0.21. Use `isSet` instead.
      * @param name
      */
     isDefault(name: keyof TypeDocOptions): boolean;
@@ -223,6 +226,19 @@ export class Options {
         );
     }
 
+    /**
+     * Checks if the given option's value is deeply strict equal to the default.
+     * @param name
+     */
+    isSet(name: keyof TypeDocOptions): boolean;
+    isSet(name: NeverIfInternal<string>): boolean;
+    isSet(name: string): boolean {
+        if (!this._declarations.has(name)) {
+            throw new Error("Tried to check if an undefined option was set");
+        }
+        return this._setOptions.has(name);
+    }
+
     /**
      * Gets all of the TypeDoc option values defined in this option container.
      */
@@ -268,6 +284,7 @@ export class Options {
 
         const converted = convert(value, declaration);
         this._values[declaration.name] = converted;
+        this._setOptions.add(name);
     }
 
     /**
@@ -299,6 +316,14 @@ export class Options {
         options: ts.CompilerOptions,
         projectReferences: readonly ts.ProjectReference[] | undefined
     ) {
+        // We do this here instead of in the tsconfig reader so that API consumers which
+        // supply a program to `Converter.convert` instead of letting TypeDoc create one
+        // can just set the compiler options, and not need to know about this mapping.
+        // It feels a bit like a hack... but it's better to have it here than to put it
+        // in Application or Converter.
+        if (options.stripInternal && !this.isSet("excludeInternal")) {
+            this.setValue("excludeInternal", true);
+        }
         this._fileNames = fileNames;
         this._compilerOptions = _.cloneDeep(options);
         this._projectReferences = projectReferences ?? [];

diff --git a/src/lib/utils/options/readers/tsconfig.ts b/src/lib/utils/options/readers/tsconfig.ts
@@ -35,7 +35,7 @@ export class TSConfigReader implements OptionsReader {
 
         if (!fileToRead || !isFile(fileToRead)) {
             // If the user didn't give us this option, we shouldn't complain about not being able to find it.
-            if (!container.isDefault("tsconfig")) {
+            if (container.isSet("tsconfig")) {
                 logger.error(`The tsconfig file ${file} does not exist`);
             }
             return;

diff --git a/src/lib/utils/options/readers/typedoc.ts b/src/lib/utils/options/readers/typedoc.ts
@@ -28,7 +28,7 @@ export class TypeDocReader implements OptionsReader {
         const file = this.findTypedocFile(path);
 
         if (!file) {
-            if (!container.isDefault("options")) {
+            if (container.isSet("options")) {
                 logger.error(
                     `The options file could not be found with the given path ${path}`
                 );

diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts
@@ -49,6 +49,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
             "Prevent symbols that are not explicitly documented from appearing in the results.",
         type: ParameterType.Boolean,
     });
+    options.addDeclaration({
+        name: "excludeInternal",
+        help:
+            "Prevent symbols that marked with @internal from being documented.",
+        type: ParameterType.Boolean,
+    });
     options.addDeclaration({
         name: "excludePrivate",
         help: "Ignores private variables and methods",

diff --git a/src/test/utils/options/options.test.ts b/src/test/utils/options/options.test.ts
@@ -96,4 +96,22 @@ describe("Options", () => {
     it("Supports directly getting values", () => {
         equal(options.getRawValues().toc, []);
     });
+
+    it("[Deprecated] Supports checking if a value is default", () => {
+        options.setValue("excludePrivate", true);
+        equal(options.isDefault("excludePrivate"), false);
+        equal(options.isDefault("excludeProtected"), true);
+    });
+
+    it("Supports checking if an option is set", () => {
+        const options = new Options(new Logger());
+        options.addDefaultDeclarations();
+        equal(options.isSet("excludePrivate"), false);
+        options.setValue("excludePrivate", false);
+        equal(options.isSet("excludePrivate"), true);
+        options.reset();
+        equal(options.isSet("excludePrivate"), false);
+
+        throws(() => options.isSet("does not exist" as never));
+    });
 });
diff --git a/src/test/utils/options/readers/data/stripInternal.tsconfig.json b/src/test/utils/options/readers/data/stripInternal.tsconfig.json
@@ -0,0 +1,6 @@
+{
+    "$schema": "http://json.schemastore.org/tsconfig",
+    "compilerOptions": {
+        "stripInternal": true
+    }
+}
diff --git a/src/test/utils/options/readers/data/valid.json b/src/test/utils/options/readers/data/valid.json
@@ -1,4 +1,4 @@
 {
-    "$schema": "https://json.schemastore.org/typedoc",
+    "$schema": "https://typedoc.org/schema.json",
     "gitRevision": "master"
 }
diff --git a/src/test/utils/options/readers/tsconfig.test.ts b/src/test/utils/options/readers/tsconfig.test.ts
@@ -38,8 +38,8 @@ describe("Options - TSConfigReader", () => {
 
     it("Does not error if the option file cannot be found but was not set.", () => {
         const options = new (class LyingOptions extends Options {
-            isDefault() {
-                return true;
+            isSet() {
+                return false;
             }
         })(new Logger());
         options.addDefaultDeclarations();
@@ -66,4 +66,25 @@ describe("Options - TSConfigReader", () => {
             [resolve(__dirname, "./data/file.ts")]
         );
     });
+
+    it("Allows stripInternal to set excludeInternal", () => {
+        options.reset();
+        options.setValue(
+            "tsconfig",
+            join(__dirname, "data/stripInternal.tsconfig.json")
+        );
+        options.read(new Logger());
+        equal(options.getValue("excludeInternal"), true);
+    });
+
+    it("Does not set excludeInternal by stripInternal if already set", () => {
+        options.reset();
+        options.setValue(
+            "tsconfig",
+            join(__dirname, "data/stripInternal.tsconfig.json")
+        );
+        options.setValue("excludeInternal", false);
+        options.read(new Logger());
+        equal(options.getValue("excludeInternal"), false);
+    });
 });
diff --git a/src/test/utils/options/readers/typedoc.test.ts b/src/test/utils/options/readers/typedoc.test.ts
@@ -52,8 +52,8 @@ describe("Options - TypeDocReader", () => {
 
     it("Does not error if the option file cannot be found but was not set.", () => {
         const options = new (class LyingOptions extends Options {
-            isDefault() {
-                return true;
+            isSet() {
+                return false;
             }
         })(new Logger());