From 7085cefb5f0d3c6b40ac893c88d3d1e866faedb9 Mon Sep 17 00:00:00 2001
From: Matthieu Riegler <kyro38@gmail.com>
Date: Mon, 18 May 2026 00:43:50 +0200
Subject: [PATCH] docs(docs-infra): Show function args

With this change non-overloaded functions also show the params + return type in a dedicated block.
---
 .../rendering/entities/renderables.mts        |  2 +-
 .../rendering/templates/class-method-info.tsx |  8 ++-
 .../templates/function-reference.tsx          | 72 +++++++++++--------
 .../api-gen/rendering/templates/parameter.tsx |  6 +-
 .../transforms/function-transforms.mts        | 14 ++--
 .../rendering/transforms/jsdoc-transforms.mts |  2 +-
 .../transforms/params-transforms.mts          | 12 +++-
 adev/shared-docs/styles/_reference.scss       |  5 ++
 8 files changed, 79 insertions(+), 42 deletions(-)

diff --git a/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts b/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts
index 13b7f61b9ede..7aaed62791d3 100644
--- a/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts
+++ b/adev/shared-docs/pipeline/api-gen/rendering/entities/renderables.mts
@@ -21,7 +21,6 @@ import {
   ParameterEntry,
   PipeEntry,
   TypeAliasEntry,
-  EntryType,
 } from '../entities.mjs';
 
 import {CliCommand, CliOption} from '../cli-entities.mjs';
@@ -105,6 +104,7 @@ export type FunctionEntryRenderable = FunctionEntry &
 export type FunctionSignatureMetadataRenderable = FunctionSignatureMetadata &
   DocEntryRenderable & {
     params: ParameterEntryRenderable[];
+    htmlReturnDescription?: string;
   };
 
 /** Documentation entity for a block augmented with transformed content for rendering. */
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/templates/class-method-info.tsx b/adev/shared-docs/pipeline/api-gen/rendering/templates/class-method-info.tsx
index e64dd38b4b3c..ac11d3900065 100644
--- a/adev/shared-docs/pipeline/api-gen/rendering/templates/class-method-info.tsx
+++ b/adev/shared-docs/pipeline/api-gen/rendering/templates/class-method-info.tsx
@@ -23,6 +23,7 @@ import {RawHtml} from './raw-html';
 export function ClassMethodInfo(props: {
   entry: FunctionSignatureMetadataRenderable;
   hideUsageNotes?: boolean;
+  hideDescription?: boolean;
 }) {
   const entry = props.entry;
 
@@ -30,7 +31,9 @@ export function ClassMethodInfo(props: {
     <div
       className={`${REFERENCE_MEMBER_CARD_ITEM} ${entry.deprecated ? 'docs-reference-card-item-deprecated' : ''}`}
     >
-      <RawHtml value={entry.htmlDescription} className={'docs-function-definition'} />
+      {!props.hideDescription && (
+        <RawHtml value={entry.htmlDescription} className={'docs-function-definition'} />
+      )}
       {/* In case when method is overloaded we need to indicate which overload is deprecated */}
       {entry.deprecated ? (
         <div>
@@ -45,6 +48,9 @@ export function ClassMethodInfo(props: {
       <div className={'docs-return-type'}>
         <span className={PARAM_KEYWORD_CLASS_NAME}>@returns</span>
         <CodeSymbol code={entry.returnType} />
+        {entry.htmlReturnDescription && (
+          <RawHtml value={entry.htmlReturnDescription} className="docs-parameter-description" />
+        )}
       </div>
       {entry.htmlUsageNotes && !props.hideUsageNotes ? (
         <div className={'docs-usage-notes'}>
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/templates/function-reference.tsx b/adev/shared-docs/pipeline/api-gen/rendering/templates/function-reference.tsx
index 408f9baa7694..10cbd2242172 100644
--- a/adev/shared-docs/pipeline/api-gen/rendering/templates/function-reference.tsx
+++ b/adev/shared-docs/pipeline/api-gen/rendering/templates/function-reference.tsx
@@ -32,31 +32,43 @@ import {SectionUsageNotes} from './section-usage-notes';
 export const signatureCard = (
   name: string,
   signature: FunctionSignatureMetadataRenderable,
-  opts: {id: string; printSignaturesAsHeader: boolean; hideUsageNotes?: boolean},
+  opts: {
+    id: string;
+    printSignaturesAsHeader: boolean;
+    hideUsageNotes?: boolean;
+    hideHeader?: boolean;
+    hideDescription?: boolean;
+  },
 ) => {
   return (
     <div id={opts.id} class={REFERENCE_MEMBER_CARD}>
-      <header class={REFERENCE_MEMBER_CARD_HEADER}>
-        {opts.printSignaturesAsHeader ? (
-          <HighlightTypeScript
-            code={printInitializerFunctionSignatureLine(
-              name,
-              signature,
-              // Always omit types in signature headers, to keep them short.
-              true,
-            )}
-          />
-        ) : (
-          <>
-            <h3>{name}</h3>
-            <div>
-              <CodeSymbol code={signature.returnType} />
-            </div>
-          </>
-        )}
-      </header>
+      {!opts.hideHeader && (
+        <header class={REFERENCE_MEMBER_CARD_HEADER}>
+          {opts.printSignaturesAsHeader ? (
+            <HighlightTypeScript
+              code={printInitializerFunctionSignatureLine(
+                name,
+                signature,
+                // Always omit types in signature headers, to keep them short.
+                true,
+              )}
+            />
+          ) : (
+            <>
+              <h3>{name}</h3>
+              <div>
+                <CodeSymbol code={signature.returnType} />
+              </div>
+            </>
+          )}
+        </header>
+      )}
       <div class={REFERENCE_MEMBER_CARD_BODY}>
-        <ClassMethodInfo entry={signature} hideUsageNotes={opts.hideUsageNotes} />
+        <ClassMethodInfo
+          entry={signature}
+          hideUsageNotes={opts.hideUsageNotes}
+          hideDescription={opts.hideDescription}
+        />
       </div>
     </div>
   );
@@ -64,7 +76,6 @@ export const signatureCard = (
 
 /** Component to render a function API reference document. */
 export function FunctionReference(entry: FunctionEntryRenderable) {
-  // Use signatures as header if there are multiple signatures.
   const printSignaturesAsHeader = entry.signatures.length > 1;
 
   return (
@@ -73,14 +84,15 @@ export function FunctionReference(entry: FunctionEntryRenderable) {
       <DeprecationWarning entry={entry} />
       <SectionApi entry={entry} />
       <div className={REFERENCE_MEMBERS}>
-        {entry.signatures.length > 1 &&
-          entry.signatures.map((s, i) =>
-            signatureCard(s.name, getFunctionMetadataRenderable(s, entry.moduleName, entry.repo), {
-              id: `${s.name}_${i}`,
-              printSignaturesAsHeader,
-              hideUsageNotes: true,
-            }),
-          )}
+        {entry.signatures.map((s, i) =>
+          signatureCard(s.name, getFunctionMetadataRenderable(s, entry.moduleName, entry.repo), {
+            id: `${s.name}_${i}`,
+            printSignaturesAsHeader,
+            hideHeader: !printSignaturesAsHeader,
+            hideUsageNotes: true,
+            hideDescription: true,
+          }),
+        )}
       </div>
 
       <SectionDescription entry={entry} />
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/templates/parameter.tsx b/adev/shared-docs/pipeline/api-gen/rendering/templates/parameter.tsx
index 0c8f5356ffa3..db717533dc49 100644
--- a/adev/shared-docs/pipeline/api-gen/rendering/templates/parameter.tsx
+++ b/adev/shared-docs/pipeline/api-gen/rendering/templates/parameter.tsx
@@ -8,9 +8,9 @@
 
 import {h} from 'preact';
 import {ParameterEntryRenderable} from '../entities/renderables.mjs';
-import {RawHtml} from './raw-html';
 import {PARAM_GROUP_CLASS_NAME} from '../styling/css-classes.mjs';
 import {CodeSymbol} from './code-symbols';
+import {RawHtml} from './raw-html';
 
 /** Component to render a function or method parameter reference doc fragment. */
 export function Parameter(props: {param: ParameterEntryRenderable}) {
@@ -21,7 +21,9 @@ export function Parameter(props: {param: ParameterEntryRenderable}) {
       {/*TODO: isOptional, isRestParam*/}
       <span class="docs-param-keyword">@param</span>
       <span class="docs-param-name">{param.name}</span>
-      <CodeSymbol code={param.type} />
+      <span class="docs-param-type">
+        <CodeSymbol code={param.type} />
+      </span>
       <RawHtml value={param.htmlDescription} className="docs-parameter-description" />
     </div>
   );
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/function-transforms.mts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/function-transforms.mts
index 46befb4cdbb5..22ea35dc19d4 100644
--- a/adev/shared-docs/pipeline/api-gen/rendering/transforms/function-transforms.mts
+++ b/adev/shared-docs/pipeline/api-gen/rendering/transforms/function-transforms.mts
@@ -20,7 +20,7 @@ import {
   setEntryFlags,
 } from './jsdoc-transforms.mjs';
 import {addModuleName} from './module-name.mjs';
-import {addRenderableFunctionParams} from './params-transforms.mjs';
+import {addHtmlReturnDescription, addRenderableFunctionParams} from './params-transforms.mjs';
 import {addRepo} from './repo.mjs';
 
 /** Given an unprocessed function entry, get the fully renderable function entry. */
@@ -50,11 +50,13 @@ export function getFunctionMetadataRenderable(
   repo: string,
 ): FunctionSignatureMetadataRenderable {
   return addHtmlAdditionalLinks(
-    addRenderableFunctionParams(
-      addHtmlUsageNotes(
-        setEntryFlags(
-          addHtmlJsDocTagComments(
-            addHtmlDescription(addRepo(addModuleName(entry, moduleName), repo)),
+    addHtmlReturnDescription(
+      addRenderableFunctionParams(
+        addHtmlUsageNotes(
+          setEntryFlags(
+            addHtmlJsDocTagComments(
+              addHtmlDescription(addRepo(addModuleName(entry, moduleName), repo)),
+            ),
           ),
         ),
       ),
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.mts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.mts
index 5f067da7bb0c..cee207415b9d 100644
--- a/adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.mts
+++ b/adev/shared-docs/pipeline/api-gen/rendering/transforms/jsdoc-transforms.mts
@@ -112,7 +112,7 @@ export function addHtmlUsageNotes<T extends HasJsDocTags>(entry: T): T & HasHtml
 }
 
 /** Given a markdown JsDoc text, gets the rendered HTML. */
-function getHtmlForJsDocText(text: string): string {
+export function getHtmlForJsDocText(text: string): string {
   const mdToParse = convertLinks(wrapExampleHtmlElementsWithCode(text));
   const parsed = parseMarkdown(mdToParse, {
     apiEntries: getSymbolsAsApiEntries(),
diff --git a/adev/shared-docs/pipeline/api-gen/rendering/transforms/params-transforms.mts b/adev/shared-docs/pipeline/api-gen/rendering/transforms/params-transforms.mts
index 3048b70cef0f..2b374d2c8529 100644
--- a/adev/shared-docs/pipeline/api-gen/rendering/transforms/params-transforms.mts
+++ b/adev/shared-docs/pipeline/api-gen/rendering/transforms/params-transforms.mts
@@ -7,7 +7,7 @@
  */
 
 import {HasModuleName, HasParams, HasRenderableParams} from '../entities/traits.mjs';
-import {addHtmlDescription} from './jsdoc-transforms.mjs';
+import {addHtmlDescription, getHtmlForJsDocText} from './jsdoc-transforms.mjs';
 import {addModuleName} from './module-name.mjs';
 
 export function addRenderableFunctionParams<T extends HasParams & HasModuleName>(
@@ -22,3 +22,13 @@ export function addRenderableFunctionParams<T extends HasParams & HasModuleName>
     params,
   };
 }
+
+/** Converts `returnDescription` to `htmlReturnDescription` for rendering. */
+export function addHtmlReturnDescription<
+  T extends {returnDescription?: string; moduleName: string},
+>(entry: T): T & {htmlReturnDescription?: string} {
+  const htmlReturnDescription = entry.returnDescription
+    ? getHtmlForJsDocText(entry.returnDescription)
+    : undefined;
+  return {...entry, htmlReturnDescription};
+}
diff --git a/adev/shared-docs/styles/_reference.scss b/adev/shared-docs/styles/_reference.scss
index fe251c4e0796..8bed9e061dc6 100644
--- a/adev/shared-docs/styles/_reference.scss
+++ b/adev/shared-docs/styles/_reference.scss
@@ -340,6 +340,11 @@
           }
         }
 
+        .docs-param-type {
+          display: inline-block;
+          margin-inline-end: 0.5rem;
+        }
+
         .docs-parameter-description {
           p:first-child {
             margin-block-start: 0;