Merge @returns and return type blocks in output

Resolves #2180

Author: Gerrit0

CHANGELOG.md

@@ -3,13 +3,15 @@
 ### Features
 
 -   Added support for discovering a "module" comment on global files, #2165.
+-   Function `@returns` blocks will now be rendered with the return type, #2180.
 
 ### Bug Fixes
 
 -   Type parameter constraints now respect the `--hideParameterTypesInTitle` option, #2226.
 -   Even more contrast fixes, #2248.
 -   Fix semantic highlighting for predicate type's parameter references, #2249.
 -   Fixed inconsistent styling between type parameter lists and parameter lists.
+-   TypeDoc will now warn if more than one `@returns` block is is present in a function, and ignore the duplicate blocks as specified by TSDoc.
 
 ## v0.24.4 (2023-04-16)
 

src/lib/converter/comments/parser.ts

@@ -154,6 +154,14 @@ function postProcessComment(comment: Comment, warning: (msg: string) => void) {
         removeIf(comment.blockTags, (tag) => remarks.indexOf(tag) > 0);
     }
 
+    const returns = comment.blockTags.filter((tag) => tag.tag === "@returns");
+    if (remarks.length > 1) {
+        warning(
+            "At most one @returns tag is expected in a comment, ignoring all but the first"
+        );
+        removeIf(comment.blockTags, (tag) => returns.indexOf(tag) > 0);
+    }
+
     const inheritDoc = comment.blockTags.filter(
         (tag) => tag.tag === "@inheritDoc"
     );

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

@@ -1,17 +1,21 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
 import { JSX, Raw } from "../../../../utils";
-import type { Reflection } from "../../../../models";
+import { Reflection, ReflectionKind } from "../../../../models";
 import { camelToTitleCase } from "../../lib";
 
 export function comment({ markdown }: DefaultThemeRenderContext, props: Reflection) {
     if (!props.comment?.hasVisibleComponent()) return;
 
     // Note: Comment modifiers are handled in `renderFlags`
 
+    const tags = props.kindOf(ReflectionKind.SomeSignature)
+        ? props.comment.blockTags.filter((tag) => tag.tag !== "@returns")
+        : props.comment.blockTags;
+
     return (
         <div class="tsd-comment tsd-typography">
             <Raw html={markdown(props.comment.summary)} />
-            {props.comment.blockTags.map((item) => (
+            {tags.map((item) => (
                 <>
                     <h3>{camelToTitleCase(item.tag.substring(1))}</h3>
                     <Raw html={markdown(item.content)} />

src/lib/output/themes/default/partials/member.signature.body.tsx

@@ -1,54 +1,59 @@
 import type { DefaultThemeRenderContext } from "../DefaultThemeRenderContext";
-import { JSX } from "../../../../utils";
+import { JSX, Raw } from "../../../../utils";
 import { ReflectionType, SignatureReflection } from "../../../../models";
 import { hasTypeParameters, renderFlags } from "../../lib";
 
-export const memberSignatureBody = (
+export function memberSignatureBody(
     context: DefaultThemeRenderContext,
     props: SignatureReflection,
     { hideSources = false }: { hideSources?: boolean } = {}
-) => (
-    <>
-        {renderFlags(props.flags, props.comment)}
-        {context.comment(props)}
+) {
+    const returnsTag = props.comment?.getTag("@returns");
 
-        {hasTypeParameters(props) && context.typeParameters(props.typeParameters)}
+    return (
+        <>
+            {renderFlags(props.flags, props.comment)}
+            {context.comment(props)}
 
-        {props.parameters && props.parameters.length > 0 && (
-            <div class="tsd-parameters">
-                <h4 class="tsd-parameters-title">Parameters</h4>
-                <ul class="tsd-parameter-list">
-                    {props.parameters.map((item) => (
-                        <li>
-                            <h5>
-                                {renderFlags(item.flags, item.comment)}
-                                {!!item.flags.isRest && <span class="tsd-signature-symbol">...</span>}
-                                <span class="tsd-kind-parameter">{item.name}</span>
-                                {": "}
-                                {context.type(item.type)}
-                                {item.defaultValue != null && (
-                                    <span class="tsd-signature-symbol">
-                                        {" = "}
-                                        {item.defaultValue}
-                                    </span>
-                                )}
-                            </h5>
-                            {context.comment(item)}
-                            {item.type instanceof ReflectionType && context.parameter(item.type.declaration)}
-                        </li>
-                    ))}
-                </ul>
-            </div>
-        )}
-        {props.type && (
-            <>
-                <h4 class="tsd-returns-title">
-                    {"Returns "}
-                    {context.type(props.type)}
-                </h4>
-                {props.type instanceof ReflectionType && context.parameter(props.type.declaration)}
-            </>
-        )}
-        {!hideSources && context.memberSources(props)}
-    </>
-);
+            {hasTypeParameters(props) && context.typeParameters(props.typeParameters)}
+
+            {props.parameters && props.parameters.length > 0 && (
+                <div class="tsd-parameters">
+                    <h4 class="tsd-parameters-title">Parameters</h4>
+                    <ul class="tsd-parameter-list">
+                        {props.parameters.map((item) => (
+                            <li>
+                                <h5>
+                                    {renderFlags(item.flags, item.comment)}
+                                    {!!item.flags.isRest && <span class="tsd-signature-symbol">...</span>}
+                                    <span class="tsd-kind-parameter">{item.name}</span>
+                                    {": "}
+                                    {context.type(item.type)}
+                                    {item.defaultValue != null && (
+                                        <span class="tsd-signature-symbol">
+                                            {" = "}
+                                            {item.defaultValue}
+                                        </span>
+                                    )}
+                                </h5>
+                                {context.comment(item)}
+                                {item.type instanceof ReflectionType && context.parameter(item.type.declaration)}
+                            </li>
+                        ))}
+                    </ul>
+                </div>
+            )}
+            {props.type && (
+                <>
+                    <h4 class="tsd-returns-title">
+                        {"Returns "}
+                        {context.type(props.type)}
+                    </h4>
+                    {returnsTag && <Raw html={context.markdown(returnsTag.content)} />}
+                    {props.type instanceof ReflectionType && context.parameter(props.type.declaration)}
+                </>
+            )}
+            {!hideSources && context.memberSources(props)}
+        </>
+    );
+}