Implement intentionallyNotDocumented option

Resolves #2863

Author: Gerrit0

site/options/package-options.md

@@ -143,6 +143,7 @@ at the root level. The following tables indicate where an option should be set.
 | [`treatValidationWarningsAsErrors`](validation.md#treatvalidationwarningsaserrors) | Root     |                                                                                                                                        |
 | [`intentionallyNotExported`](validation.md#intentionallynotexported)               | Both     |                                                                                                                                        |
 | [`requiredToBeDocumented`](validation.md#requiredtobedocumented)                   | Both     |                                                                                                                                        |
+| [`intentionallyNotDocumented`](validation.md#intentionallynotdocumented)           | Both     |                                                                                                                                        |
 
 ## Other Options
 

site/options/validation.md

@@ -123,3 +123,15 @@ typedoc.json:
     ]
 }
 ```
+
+## intentionallyNotDocumented
+
+Used to selectively ignore undocumented fields, used by `validation.notDocumented`.
+This should include the qualified name printed when a member is not documented if it cannot be
+or should not be documented normally.
+
+```json
+{
+    "intentionallyNotDocumented": ["Namespace.Class.prop"]
+}
+```

src/lib/application.ts

@@ -685,6 +685,7 @@ export class Application extends AbstractComponent<
                 project,
                 this.logger,
                 this.options.getValue("requiredToBeDocumented"),
+                this.options.getValue("intentionallyNotDocumented"),
             );
         }
 

src/lib/internationalization/locales/en.cts

@@ -94,6 +94,8 @@ export = {
     failed_to_resolve_link_to_0_in_document_1_may_have_meant_2: `Failed to resolve link to "{0}" in document {1}. You may have wanted "{2}"`,
     type_0_defined_in_1_is_referenced_by_2_but_not_included_in_docs: `{0}, defined in {1}, is referenced by {2} but not included in the documentation`,
     reflection_0_kind_1_defined_in_2_does_not_have_any_documentation: `{0} ({1}), defined in {2}, does not have any documentation`,
+    invalid_intentionally_not_documented_names_0:
+        "The following qualified reflection names were marked as intentionally not documented, but were either not referenced in the documentation, or were documented:\n\t{0}",
     invalid_intentionally_not_exported_symbols_0:
         "The following symbols were marked as intentionally not exported, but were either not referenced in the documentation, or were exported:\n\t{0}",
     reflection_0_has_unused_mergeModuleWith_tag:
@@ -375,6 +377,8 @@ export = {
         "A list of types which should not produce 'referenced but not documented' warnings",
     help_requiredToBeDocumented:
         "A list of reflection kinds that must be documented",
+    help_intentionallyNotDocumented:
+        "A list of full reflection names which should not produce warnings about not being documented",
     help_validation:
         "Specify which validation steps TypeDoc should perform on your generated documentation",
 

src/lib/utils/options/declaration.ts

@@ -246,6 +246,7 @@ export interface TypeDocOptionMap {
     intentionallyNotExported: string[];
     validation: ValidationOptions;
     requiredToBeDocumented: ReflectionKind.KindString[];
+    intentionallyNotDocumented: string[];
 
     // Other
     watch: boolean;

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

@@ -978,6 +978,12 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         },
         defaultValue: OptionDefaults.requiredToBeDocumented,
     });
+    options.addDeclaration({
+        name: "intentionallyNotDocumented",
+        help: (i18n) => i18n.help_intentionallyNotDocumented(),
+        type: ParameterType.Array,
+        defaultValue: [],
+    });
 
     options.addDeclaration({
         name: "validation",

src/lib/validation/documentation.ts

@@ -13,6 +13,7 @@ export function validateDocumentation(
     project: ProjectReflection,
     logger: Logger,
     requiredToBeDocumented: readonly ReflectionKind.KindString[],
+    intentionallyNotDocumented: readonly string[],
 ): void {
     let kinds = requiredToBeDocumented.reduce(
         (prev, cur) => prev | ReflectionKind[cur],
@@ -37,6 +38,7 @@ export function validateDocumentation(
 
     const toProcess = project.getReflectionsByKind(kinds);
     const seen = new Set<Reflection>();
+    const intentionalUsage = new Set<number>();
 
     outer: while (toProcess.length) {
         const ref = toProcess.shift()!;
@@ -111,6 +113,14 @@ export function validateDocumentation(
                 continue;
             }
 
+            const intentionalIndex = intentionallyNotDocumented.indexOf(
+                ref.getFriendlyFullName(),
+            );
+            if (intentionalIndex !== -1) {
+                intentionalUsage.add(intentionalIndex);
+                continue;
+            }
+
             logger.warn(
                 logger.i18n.reflection_0_kind_1_defined_in_2_does_not_have_any_documentation(
                     ref.getFriendlyFullName(),
@@ -120,4 +130,15 @@ export function validateDocumentation(
             );
         }
     }
+
+    const unusedIntentional = intentionallyNotDocumented.filter(
+        (_, i) => !intentionalUsage.has(i),
+    );
+    if (unusedIntentional.length) {
+        logger.warn(
+            logger.i18n.invalid_intentionally_not_documented_names_0(
+                unusedIntentional.join("\n\t"),
+            ),
+        );
+    }
 }

src/test/converter2/validation/intentionallyNotDocumented.ts

@@ -0,0 +1,5 @@
+/** Foo doc */
+export interface Foo {
+    notDoc: string;
+    notDoc2: string;
+}

src/test/validation.test.ts

@@ -156,7 +156,7 @@ describe("validateDocumentation", () => {
     it("Should correctly handle functions", () => {
         const project = convertValidationFile("function.ts");
         const logger = new TestLogger();
-        validateDocumentation(project, logger, ["Function"]);
+        validateDocumentation(project, logger, ["Function"], []);
 
         logger.expectMessage(
             "warn: bar (CallSignature), defined in */function.ts, does not have any documentation",
@@ -167,7 +167,7 @@ describe("validateDocumentation", () => {
     it("Should correctly handle accessors", () => {
         const project = convertValidationFile("getSignature.ts");
         const logger = new TestLogger();
-        validateDocumentation(project, logger, ["Accessor"]);
+        validateDocumentation(project, logger, ["Accessor"], []);
 
         logger.expectMessage(
             "warn: Foo.foo (GetSignature), defined in */getSignature.ts, does not have any documentation",
@@ -178,7 +178,7 @@ describe("validateDocumentation", () => {
     it("Should correctly handle constructors", () => {
         const project = convertValidationFile("class.ts");
         const logger = new TestLogger();
-        validateDocumentation(project, logger, ["Constructor"]);
+        validateDocumentation(project, logger, ["Constructor"], []);
 
         logger.expectMessage(
             "warn: Foo.constructor (ConstructorSignature), defined in */class.ts, does not have any documentation",
@@ -189,7 +189,7 @@ describe("validateDocumentation", () => {
     it("Should correctly handle interfaces", () => {
         const project = convertValidationFile("interface.ts");
         const logger = new TestLogger();
-        validateDocumentation(project, logger, ["Method"]);
+        validateDocumentation(project, logger, ["Method"], []);
 
         logger.expectMessage(
             "warn: Foo.method (CallSignature), defined in */interface.ts, does not have any documentation",
@@ -200,8 +200,26 @@ describe("validateDocumentation", () => {
     it("Should correctly handle callback parameters", () => {
         const project = convertValidationFile("callbackParameters.ts");
         const logger = new TestLogger();
-        validateDocumentation(project, logger, ["Parameter", "Property"]);
+        validateDocumentation(project, logger, ["Parameter", "Property"], []);
 
         logger.expectNoOtherMessages();
     });
+
+    it("#2863 supports intentionallyNotDocumented", () => {
+        const project = convertValidationFile("intentionallyNotDocumented.ts");
+
+        const logger = new TestLogger();
+        validateDocumentation(
+            project,
+            logger,
+            ["Property"],
+            ["Foo.notDoc", "Foo.doesNotExist"],
+        );
+
+        logger.expectMessage(
+            "warn: Foo.notDoc2 * does not have any documentation",
+        );
+        logger.expectMessage("warn: The following qualified*Foo.doesNotExist");
+        logger.expectNoOtherMessages();
+    });
 });