Handle nested object @param comments

Resolves #2555

Author: Gerrit0

CHANGELOG.md

@@ -29,6 +29,7 @@ title: Changelog
 
 -   TypeDoc will now discover entry points from `package.json` exports if they
     are not provided manually, #1937.
+-   Improved support for `@param` comments with nested object types, #2555.
 -   Improved support for `@param` comments which reference a type
     alias/interface. Important properties on the referenced type can now be
     highlighted with `@param options.foo`, which will result in the additional

src/lib/converter/plugins/CommentPlugin.ts

@@ -722,7 +722,8 @@ function moveNestedParamTags(
                 for (const tag of tags) {
                     const path = tag.name!.split(".");
                     path.shift();
-                    const child = target.declaration.getChildByName(path);
+                    const child =
+                        target.declaration.getChildOrTypePropertyByName(path);
 
                     if (child && !child.comment) {
                         child.comment = new Comment(

src/lib/models/reflections/declaration.ts

@@ -192,7 +192,6 @@ export class DeclarationReflection extends ContainerReflection {
         return result;
     }
 
-    /** @internal */
     getNonIndexSignatures(): SignatureReflection[] {
         return ([] as SignatureReflection[]).concat(
             this.signatures ?? [],
@@ -201,6 +200,43 @@ export class DeclarationReflection extends ContainerReflection {
         );
     }
 
+    getProperties(): DeclarationReflection[] {
+        if (this.children?.length) {
+            return this.children;
+        }
+
+        if (this.type?.type === "reflection") {
+            return this.type.declaration.children ?? [];
+        }
+        return [];
+    }
+
+    getChildOrTypePropertyByName(
+        path: string[],
+    ): DeclarationReflection | undefined {
+        if (this.type?.type === "reflection") {
+            for (const child of this.type.declaration.children || []) {
+                if (path[0] === child.name) {
+                    if (path.length === 1) {
+                        return child;
+                    }
+                    return child.getChildOrTypePropertyByName(path.slice(1));
+                }
+            }
+        }
+
+        for (const child of this.children || []) {
+            if (path[0] === child.name) {
+                if (path.length === 1) {
+                    return child;
+                }
+                return child.getChildOrTypePropertyByName(path.slice(1));
+            }
+        }
+
+        return undefined;
+    }
+
     override traverse(callback: TraverseCallback) {
         for (const parameter of this.typeParameters?.slice() || []) {
             if (callback(parameter, TraverseProperty.TypeParameter) === false) {

src/lib/output/formatter.tsx

@@ -714,7 +714,7 @@ export class FormattedCodeBuilder {
         options: { topLevelLinks: boolean },
     ): FormatterNode {
         const members: FormatterNode[] = [];
-        const children = reflection.children || [];
+        const children = reflection.getProperties();
 
         for (const item of children) {
             this.member(members, item, options);

src/lib/output/themes/default/partials/typeDetails.tsx

@@ -88,7 +88,10 @@ export function typeDetailsImpl(
         },
         reflection(type) {
             const declaration = type.declaration;
-            return declarationDetails(context, declaration, highlighted);
+            if (highlighted) {
+                return highlightedDeclarationDetails(context, declaration, highlighted);
+            }
+            return declarationDetails(context, declaration);
         },
         reference(reference) {
             if (shouldExpandReference(reference)) {
@@ -100,8 +103,8 @@ export function typeDetailsImpl(
                 // Ensure we don't go into an infinite loop here
                 expanded.add(target);
                 const details = target.type
-                    ? typeDetailsImpl(context, target.type, reference.highlightedProperties)
-                    : declarationDetails(context, target, reference.highlightedProperties);
+                    ? typeDetailsImpl(context, target.type)
+                    : declarationDetails(context, target);
                 expanded.delete(target);
                 return details;
             }
@@ -144,23 +147,25 @@ function highlightedPropertyDetails(
     );
 }
 
-function declarationDetails(
+function highlightedDeclarationDetails(
     context: DefaultThemeRenderContext,
     declaration: DeclarationReflection,
     highlightedProperties?: Map<string, CommentDisplayPart[]>,
-): JSX.Children {
-    if (!declaration.comment?.hasModifier("@expand")) {
-        return (
-            <ul class="tsd-parameters">
-                {declaration.children?.map(
+) {
+    return (
+        <ul class="tsd-parameters">
+            {declaration
+                .getProperties()
+                ?.map(
                     (child) =>
                         highlightedProperties?.has(child.name) &&
                         renderChild(context, child, highlightedProperties.get(child.name)),
                 )}
-            </ul>
-        );
-    }
+        </ul>
+    );
+}
 
+function declarationDetails(context: DefaultThemeRenderContext, declaration: DeclarationReflection): JSX.Children {
     return (
         <>
             {context.commentSummary(declaration)}
@@ -186,9 +191,7 @@ function declarationDetails(
                     </li>
                 )}
                 {declaration.indexSignatures?.map((index) => renderIndexSignature(context, index))}
-                {declaration.children?.map((child) =>
-                    renderChild(context, child, highlightedProperties?.get(child.name)),
-                )}
+                {declaration.getProperties()?.map((child) => renderChild(context, child))}
             </ul>
         </>
     );
@@ -241,8 +244,8 @@ function renderChild(
                     {context.type(child.type)}
                 </h5>
                 {highlightOrComment(child)}
-                {child.children?.some(renderingChildIsUseful) && (
-                    <ul class="tsd-parameters">{child.children.map((c) => renderChild(context, c))}</ul>
+                {child.getProperties().some(renderingChildIsUseful) && (
+                    <ul class="tsd-parameters">{child.getProperties().map((c) => renderChild(context, c))}</ul>
                 )}
             </li>
         );
@@ -312,19 +315,20 @@ function renderIndexSignature(context: DefaultThemeRenderContext, index: Signatu
 }
 
 function renderingChildIsUseful(refl: DeclarationReflection) {
-    if (refl.hasComment()) return true;
-    if (
-        refl.children?.some((child) => {
-            if (child.hasComment()) return true;
-            if (child.type) {
-                return renderingTypeDetailsIsUseful(child.type);
-            }
-        })
-    ) {
+    if (renderingThisChildIsUseful(refl)) {
         return true;
     }
 
-    return refl.getAllSignatures().some((sig) => {
+    return refl.getProperties().some(renderingThisChildIsUseful);
+}
+
+function renderingThisChildIsUseful(refl: DeclarationReflection) {
+    if (refl.hasComment()) return true;
+
+    const declaration = refl.type?.type === "reflection" ? refl.type.declaration : refl;
+    if (declaration.hasComment()) return true;
+
+    return declaration.getAllSignatures().some((sig) => {
         return sig.hasComment() || sig.parameters?.some((p) => p.hasComment());
     });
 }

src/test/converter2/issues/gh2555.ts

@@ -0,0 +1,14 @@
+/**
+ * @param props - Component properties.
+ * @param props.title - Title.
+ * @param props.options - Options.
+ * @param props.options.featureA - Turn on or off featureA.
+ * @param props.options.featureB - Turn on or off featureB.
+ */
+export function ComponentWithOptions({
+    title,
+    options,
+}: {
+    title: string;
+    options: { featureA: boolean; featureB: boolean };
+}) {}

src/test/converter2/typedoc.json

@@ -1,4 +1,14 @@
 // This is here so we can point to it with doc:c2 and avoid warnings caused by TypeDoc's actual configuration.
 {
-    "logLevel": "Verbose"
+    "logLevel": "Verbose",
+    "outputs": [
+        {
+            "name": "html",
+            "path": "../../../docs"
+        },
+        {
+            "name": "json",
+            "path": "../../../docs/docs.json"
+        }
+    ]
 }

src/test/issues.c2.test.ts

@@ -1509,6 +1509,39 @@ describe("Issue Tests", () => {
         logger.expectNoOtherMessages();
     });
 
+    it("#2555 allows nested @param comments", () => {
+        const project = convert();
+        const sig = querySig(project, "ComponentWithOptions");
+        const param = sig.parameters?.[0];
+        equal(param?.type?.type, "reflection");
+        const title = param.type.declaration.getChildOrTypePropertyByName([
+            "title",
+        ]);
+        const options = param.type.declaration.getChildOrTypePropertyByName([
+            "options",
+        ]);
+        const featureA = param.type.declaration.getChildOrTypePropertyByName([
+            "options",
+            "featureA",
+        ]);
+        const featureB = param.type.declaration.getChildOrTypePropertyByName([
+            "options",
+            "featureB",
+        ]);
+
+        const comments = [param, title, options, featureA, featureB].map((d) =>
+            Comment.combineDisplayParts(d?.comment?.summary),
+        );
+
+        equal(comments, [
+            "Component properties.",
+            "Title.",
+            "Options.",
+            "Turn on or off featureA.",
+            "Turn on or off featureB.",
+        ]);
+    });
+
     it("#2574 default export", () => {
         const project = convert();
         const sig = querySig(project, "usesDefaultExport");