Bring back excludeCategories

Author: Gerrit0

CHANGELOG.md

@@ -16,9 +16,6 @@ title: Changelog
 -   Changed the default `sort` order to use `alphabetical-ignoring-documents`
     instead of `alphabetical`.
 -   Changed default of `suppressCommentWarningsInDeclarationFiles` to `true`
--   Removed `excludeCategories` option which has existed for over a year, but
-    GitHub indicates has only ever been used by one project and breaks with
-    changes to make categories work with packages mode.
 -   API: Constructor signatures now use the parent class name as their name
     (e.g. `X`, not `new X`)
 -   API: `@group`, `@category`, `@groupDescription` and `@categoryDescription`

src/lib/converter/plugins/CommentPlugin.ts

@@ -26,6 +26,7 @@ import { ConverterComponent } from "../components.js";
 import type { Context } from "../context.js";
 import { ConverterEvents } from "../converter-events.js";
 import type { Converter } from "../converter.js";
+import { CategoryPlugin } from "./CategoryPlugin.js";
 
 /**
  * These tags are not useful to display in the generated documentation.
@@ -137,6 +138,9 @@ export class CommentPlugin extends ConverterComponent {
     @Option("excludeNotDocumented")
     accessor excludeNotDocumented!: boolean;
 
+    @Option("excludeCategories")
+    accessor excludeCategories!: string[];
+
     @Option("defaultCategory")
     accessor defaultCategory!: string;
 
@@ -566,6 +570,10 @@ export class CommentPlugin extends ConverterComponent {
             return true;
         }
 
+        if (this.excludedByCategory(reflection)) {
+            return true;
+        }
+
         if (
             reflection.kindOf(
                 ReflectionKind.ConstructorSignature |
@@ -649,6 +657,22 @@ export class CommentPlugin extends ConverterComponent {
         return isHidden;
     }
 
+    private excludedByCategory(reflection: Reflection): boolean {
+        const excludeCategories = this.excludeCategories;
+        let target: DeclarationReflection | undefined;
+        if (reflection instanceof DeclarationReflection) {
+            target = reflection;
+        } else if (reflection instanceof SignatureReflection) {
+            target = reflection.parent;
+        }
+        if (!target || !excludeCategories.length) return false;
+        const categories = CategoryPlugin.getCategories(target);
+        if (categories.size === 0) {
+            categories.add(this.defaultCategory);
+        }
+        return excludeCategories.some((cat) => categories.has(cat));
+    }
+
     private validateParamTags(
         signature: SignatureReflection,
         comment: Comment,

src/lib/utils/options/declaration.ts

@@ -121,6 +121,7 @@ export interface TypeDocOptionMap {
     excludePrivate: boolean;
     excludeProtected: boolean;
     excludeReferences: boolean;
+    excludeCategories: string[];
     maxTypeConversionDepth: number;
     name: string;
     includeVersion: boolean;

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

@@ -192,6 +192,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         help: (i18n) => i18n.help_excludeInternal(),
         type: ParameterType.Boolean,
     });
+    options.addDeclaration({
+        name: "excludeCategories",
+        help: (i18n) => i18n.help_excludeCategories(),
+        type: ParameterType.Array,
+        defaultValue: [],
+    });
     options.addDeclaration({
         name: "excludePrivate",
         help: (i18n) => i18n.help_excludePrivate(),

src/test/behavior.c2.test.ts

@@ -436,6 +436,16 @@ describe("Behavior Tests", () => {
         logger.expectNoOtherMessages();
     });
 
+    it("Handles excludeCategories", () => {
+        app.options.setValue("excludeCategories", ["A", "Default"]);
+        app.options.setValue("defaultCategory", "Default");
+        const project = convert("excludeCategories");
+        equal(
+            project.children?.map((c) => c.name),
+            ["c"],
+        );
+    });
+
     it("Handles excludeNotDocumentedKinds", () => {
         app.options.setValue("excludeNotDocumented", true);
         app.options.setValue("excludeNotDocumentedKinds", ["Property"]);

src/test/converter2/behavior/excludeCategories.ts

@@ -0,0 +1,14 @@
+/**
+ * @category A
+ */
+export const a = 1;
+/**
+ * @category A
+ * @category B
+ */
+export const b = 1;
+/**
+ * @category C
+ */
+export const c = 1;
+export const d = 1;