Fix notDocumented validation false positive

Resolves #2291

CHANGELOG.md

@@ -13,6 +13,7 @@
 
 ### Bug Fixes
 
+-   `notDocumented` validation will no longer require documentation for data within parameters that cannot be documented via `@param`, #2291.
 -   Type parameters will now be resolved for arrow-methods on classes like regular class methods, #2320.
 -   TypeDoc now inherits `typedocOptions` fields from extended tsconfig files, #2334.
 -   Methods which return function types no longer have duplicated comments, #2336.

src/lib/validation/documentation.ts

@@ -43,17 +43,13 @@ export function validateDocumentation(
         if (seen.has(ref)) continue;
         seen.add(ref);
 
-        // If there is a parameter inside another parameter, this is probably a callback function.
-        // TypeDoc doesn't support adding comments with @param to nested parameters, so it seems
-        // silly to warn about these.
-        if (ref.kindOf(ReflectionKind.Parameter)) {
-            let r: Reflection | undefined = ref.parent;
-            while (r) {
-                if (r.kindOf(ReflectionKind.Parameter)) {
-                    continue outer;
-                }
-                r = r.parent;
+        // If we're a non-parameter inside a parameter, we shouldn't care. Parameters don't get deeply documented
+        let r: Reflection | undefined = ref.parent;
+        while (r) {
+            if (r.kindOf(ReflectionKind.Parameter)) {
+                continue outer;
             }
+            r = r.parent;
         }
 
         // Type aliases own their comments, even if they're function-likes.

src/test/converter2/issues/gh2291.ts

@@ -0,0 +1,14 @@
+/**
+ * Parses a JSON string to the specified type.
+ */
+export function safeParse<T>(
+    guard: (o: unknown) => o is T,
+    json: string,
+): T | undefined {
+    try {
+        const o = JSON.parse(json) as unknown;
+        return guard(o) ? o : undefined;
+    } catch {
+        return undefined;
+    }
+}

src/test/issues.c2.test.ts

@@ -1125,6 +1125,13 @@ describe("Issue Tests", () => {
         );
     });
 
+    it("Does not warn on notDocumented edge case #2291", () => {
+        app.options.setValue("validation", { notDocumented: true });
+        const project = convert();
+        app.validate(project);
+        logger.expectNoOtherMessages();
+    });
+
     it("Supports TS 5.0 #2296", () => {
         const project = convert();
         const names = query(project, "names");

src/test/utils/options/readers/tsconfig.test.ts

@@ -12,14 +12,22 @@ describe("Options - TSConfigReader", () => {
     options.addReader(new TSConfigReader());
     const logger = new TestLogger();
 
-    async function readWithProject(project: Project, reset = true) {
+    async function readWithProject(
+        project: Project,
+        reset = true,
+        noErrors = true,
+    ) {
         if (reset) {
             options.reset();
         }
         logger.reset();
         options.setValue("tsconfig", project.cwd);
+        project.addFile("temp.ts", "export {}");
         project.write();
         await options.read(logger);
+        if (noErrors) {
+            logger.expectNoOtherMessages();
+        }
         project.rm();
     }
 
@@ -39,7 +47,7 @@ describe("Options - TSConfigReader", () => {
         it(name, async () => {
             const project = tempdirProject();
             project.addJsonFile("tsconfig.json", file);
-            await readWithProject(project);
+            await readWithProject(project, true, false);
             equal(logger.hasErrors(), true, "No error was logged");
         });
     }
@@ -69,7 +77,7 @@ describe("Options - TSConfigReader", () => {
     it("Errors if a tsconfig file cannot be parsed", async () => {
         const project = tempdirProject();
         project.addFile("tsconfig.json", '{"test}');
-        await readWithProject(project);
+        await readWithProject(project, true, false);
         logger.expectMessage("error: *");
     });
 
@@ -164,7 +172,7 @@ describe("Options - TSConfigReader", () => {
         project.addJsonFile("tsconfig.json", {});
         project.addJsonFile("tsdoc.json", tsdoc);
 
-        await readWithProject(project, reset);
+        await readWithProject(project, reset, false);
         cb?.();
         logger.expectNoOtherMessages();
     }