Handle nested @param comments with unions

Closes #1876

Author: Gerrit0

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Unreleased
 
+### Features
+
+-   Support copying `@param` comments for nested members that target union and intersection types, #1876.
+
 ## v0.22.12 (2022-02-20)
 
 ### Features

src/lib/converter/plugins/CommentPlugin.ts

@@ -18,7 +18,7 @@ import {
 } from "../factories/comment";
 import { Converter } from "../converter";
 import type { Context } from "../context";
-import { ReflectionType, SourceReference } from "../../models";
+import { ReflectionType, SourceReference, TypeVisitor } from "../../models";
 import {
     BindOption,
     filterMap,
@@ -455,21 +455,32 @@ export class CommentPlugin extends ConverterComponent {
 
 // Moves tags like `@param foo.bar docs for bar` into the `bar` property of the `foo` parameter.
 function moveNestedParamTags(comment: Comment, parameter: ParameterReflection) {
-    if (parameter.type instanceof ReflectionType) {
-        const tags = comment.tags.filter(
-            (t) =>
-                t.tagName === "param" &&
-                t.paramName.startsWith(`${parameter.name}.`)
-        );
+    const visitor: Partial<TypeVisitor> = {
+        reflection(target) {
+            const tags = comment.tags.filter(
+                (t) =>
+                    t.tagName === "param" &&
+                    t.paramName.startsWith(`${parameter.name}.`)
+            );
 
-        for (const tag of tags) {
-            const path = tag.paramName.split(".");
-            path.shift();
-            const child = parameter.type.declaration.getChildByName(path);
+            for (const tag of tags) {
+                const path = tag.paramName.split(".");
+                path.shift();
+                const child = target.declaration.getChildByName(path);
 
-            if (child && !child.comment) {
-                child.comment = new Comment(tag.text);
+                if (child && !child.comment) {
+                    child.comment = new Comment(tag.text);
+                }
             }
-        }
-    }
+        },
+        // #1876, also do this for unions/intersections.
+        union(u) {
+            u.types.forEach((t) => t.visit(visitor));
+        },
+        intersection(i) {
+            i.types.forEach((t) => t.visit(visitor));
+        },
+    };
+
+    parameter.type?.visit(visitor);
 }

src/lib/models/types.ts

@@ -21,8 +21,10 @@ export abstract class Type {
     /**
      * Visit this type, returning the value returned by the visitor.
      */
-    visit<T>(visitor: TypeVisitor<T>): T {
-        return visitor[this.type](this as never);
+    visit<T>(visitor: TypeVisitor<T>): T;
+    visit<T>(visitor: Partial<TypeVisitor<T>>): T | undefined;
+    visit(visitor: Partial<TypeVisitor<unknown>>): unknown {
+        return visitor[this.type]?.(this as never);
     }
 }
 

src/test/converter2/issues/gh1876.ts

@@ -0,0 +1,13 @@
+/**
+ * @param options.min Nested
+ */
+export function foo(options?: number | { min?: number }): number {
+    return 0;
+}
+
+/**
+ * @param options.min Nested
+ */
+export function bar(options: { min: number; max: number } | { min: string }) {
+    return 0;
+}

src/test/issueTests.ts

@@ -8,6 +8,7 @@ import {
     ReflectionType,
     Comment,
     CommentTag,
+    UnionType,
 } from "../lib/models";
 
 function query(project: ProjectReflection, name: string) {
@@ -290,4 +291,34 @@ export const issueTests: {
         ok(project.children![0].kind === ReflectionKind.Reference);
         ok(project.children![1].kind !== ReflectionKind.Reference);
     },
+
+    gh1876(project) {
+        const foo = query(project, "foo");
+        const fooSig = foo.signatures?.[0].parameters?.[0];
+        ok(fooSig);
+        ok(fooSig.type instanceof UnionType);
+        ok(fooSig.type.types[1] instanceof ReflectionType);
+        equal(
+            fooSig.type.types[1].declaration.getChildByName("min")?.comment
+                ?.shortText,
+            "Nested\n"
+        );
+
+        const bar = query(project, "bar");
+        const barSig = bar.signatures?.[0].parameters?.[0];
+        ok(barSig);
+        ok(barSig.type instanceof UnionType);
+        ok(barSig.type.types[0] instanceof ReflectionType);
+        ok(barSig.type.types[1] instanceof ReflectionType);
+        equal(
+            barSig.type.types[0].declaration.getChildByName("min")?.comment
+                ?.shortText,
+            "Nested\n"
+        );
+        equal(
+            barSig.type.types[1].declaration.getChildByName("min")?.comment
+                ?.shortText,
+            "Nested\n"
+        );
+    },
 };