Update comment rendering for functions

Resolves #2285
TypeStrong · May 29, 2023 · c9dee38 · c9dee38
1 parent 2624c28
commit c9dee38
Show file tree

Hide file tree

Showing 10 changed files with 72 additions and 14 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -8,6 +8,8 @@
 
 ### Bug Fixes
 
+-   When rendering functions/methods, TypeDoc will now render the comment summary above the parameters/return type,
+    and any other block tags in the order they are defined in the comment, #2285.
 -   Comments are no longer removed from classes/interfaces containing call signatures, #2290.
 
 ### Thanks!

diff --git a/src/lib/application.ts b/src/lib/application.ts
@@ -153,6 +153,15 @@ export class Application extends ChildableComponent<
 
     /**
      * Initialize TypeDoc without loading plugins.
+     *
+     * @example
+     * Initialize the application with pretty-printing output disabled.
+     * ```ts
+     * const app = new Application();
+     * app.bootstrap({ pretty: false });
+     * ```
+     *
+     * @param options - Options to set during initialization
      */
     bootstrap(options: Partial<TypeDocOptions> = {}): void {
         this.options.reset();

diff --git a/src/lib/output/themes/default/DefaultThemeRenderContext.ts b/src/lib/output/themes/default/DefaultThemeRenderContext.ts
@@ -12,7 +12,7 @@ import { defaultLayout } from "./layouts/default";
 import { index } from "./partials";
 import { analytics } from "./partials/analytics";
 import { breadcrumb } from "./partials/breadcrumb";
-import { comment } from "./partials/comment";
+import { comment, commentSummary, commentTags } from "./partials/comment";
 import { footer } from "./partials/footer";
 import { header } from "./partials/header";
 import { hierarchy } from "./partials/hierarchy";
@@ -106,7 +106,10 @@ export class DefaultThemeRenderContext {
 
     analytics = bind(analytics, this);
     breadcrumb = bind(breadcrumb, this);
+    /** @deprecated will be removed in 0.25 */
     comment = bind(comment, this);
+    commentSummary = bind(commentSummary, this);
+    commentTags = bind(commentTags, this);
     footer = bind(footer, this);
     header = bind(header, this);
     hierarchy = bind(hierarchy, this);

diff --git a/src/lib/output/themes/default/partials/comment.tsx b/src/lib/output/themes/default/partials/comment.tsx
@@ -3,11 +3,11 @@ import { JSX, Raw } from "../../../../utils";
 import { Reflection, ReflectionKind } from "../../../../models";
 import { camelToTitleCase } from "../../lib";
 
+// Note: Comment modifiers are handled in `renderFlags`
+
 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;
@@ -24,3 +24,32 @@ export function comment({ markdown }: DefaultThemeRenderContext, props: Reflecti
         </div>
     );
 }
+
+export function commentSummary({ markdown }: DefaultThemeRenderContext, props: Reflection) {
+    if (!props.comment?.summary.some((part) => part.text)) return;
+
+    return (
+        <div class="tsd-comment tsd-typography">
+            <Raw html={markdown(props.comment.summary)} />
+        </div>
+    );
+}
+
+export function commentTags({ markdown }: DefaultThemeRenderContext, props: Reflection) {
+    if (!props.comment) return;
+
+    const tags = props.kindOf(ReflectionKind.SomeSignature)
+        ? props.comment.blockTags.filter((tag) => tag.tag !== "@returns")
+        : props.comment.blockTags;
+
+    return (
+        <div class="tsd-comment tsd-typography">
+            {tags.map((item) => (
+                <>
+                    <h4>{camelToTitleCase(item.tag.substring(1))}</h4>
+                    <Raw html={markdown(item.content)} />
+                </>
+            ))}
+        </div>
+    );
+}
diff --git a/src/lib/output/themes/default/partials/member.declaration.tsx b/src/lib/output/themes/default/partials/member.declaration.tsx
@@ -24,7 +24,7 @@ export const memberDeclaration = (context: DefaultThemeRenderContext, props: Dec
             )}
         </div>
 
-        {context.comment(props)}
+        {context.commentSummary(props)}
 
         {hasTypeParameters(props) && context.typeParameters(props.typeParameters)}
 
@@ -35,6 +35,8 @@ export const memberDeclaration = (context: DefaultThemeRenderContext, props: Dec
             </div>
         )}
 
+        {context.commentTags(props)}
+
         {context.memberSources(props)}
     </>
 );
diff --git a/src/lib/output/themes/default/partials/member.signature.body.tsx b/src/lib/output/themes/default/partials/member.signature.body.tsx
@@ -13,7 +13,7 @@ export function memberSignatureBody(
     return (
         <>
             {renderFlags(props.flags, props.comment)}
-            {context.comment(props)}
+            {context.commentSummary(props)}
 
             {hasTypeParameters(props) && context.typeParameters(props.typeParameters)}
 
@@ -36,7 +36,8 @@ export function memberSignatureBody(
                                         </span>
                                     )}
                                 </h5>
-                                {context.comment(item)}
+                                {context.commentSummary(item)}
+                                {context.commentTags(item)}
                                 {item.type instanceof ReflectionType && context.parameter(item.type.declaration)}
                             </li>
                         ))}
@@ -53,6 +54,9 @@ export function memberSignatureBody(
                     {props.type instanceof ReflectionType && context.parameter(props.type.declaration)}
                 </>
             )}
+
+            {context.commentTags(props)}
+
             {!hideSources && context.memberSources(props)}
         </>
     );

diff --git a/src/lib/output/themes/default/partials/parameter.tsx b/src/lib/output/themes/default/partials/parameter.tsx
@@ -42,7 +42,8 @@ export const parameter = (context: DefaultThemeRenderContext, props: Declaration
                             <span class="tsd-signature-symbol">{"]: "}</span>
                             {context.type(props.indexSignature.type)}
                         </h5>
-                        {context.comment(props.indexSignature)}
+                        {context.commentSummary(props.indexSignature)}
+                        {context.commentTags(props.indexSignature)}
                         {props.indexSignature.type instanceof ReflectionType &&
                             context.parameter(props.indexSignature.type.declaration)}
                     </li>
@@ -75,7 +76,8 @@ export const parameter = (context: DefaultThemeRenderContext, props: Declaration
                                     </span>
                                     {context.type(item.type)}
                                 </h5>
-                                {context.comment(item)}
+                                {context.commentSummary(item)}
+                                {context.commentTags(item)}
                                 {!!item.children && context.parameter(item)}
                                 {item.type instanceof ReflectionType && context.parameter(item.type.declaration)}
                             </li>
@@ -95,7 +97,8 @@ export const parameter = (context: DefaultThemeRenderContext, props: Declaration
                                             {context.type(item.getSignature.type)}
                                         </h5>
 
-                                        {context.comment(item.getSignature)}
+                                        {context.commentSummary(item.getSignature)}
+                                        {context.commentTags(item.getSignature)}
                                     </li>
                                 </>
                             )}
@@ -119,7 +122,8 @@ export const parameter = (context: DefaultThemeRenderContext, props: Declaration
                                             {context.type(item.setSignature.type)}
                                         </h5>
 
-                                        {context.comment(item.setSignature)}
+                                        {context.commentSummary(item.setSignature)}
+                                        {context.commentTags(item.setSignature)}
                                     </li>
                                 </>
                             )}

diff --git a/src/lib/output/themes/default/partials/typeParameters.tsx b/src/lib/output/themes/default/partials/typeParameters.tsx
@@ -27,7 +27,8 @@ export function typeParameters(context: DefaultThemeRenderContext, typeParameter
                                     </>
                                 )}
                             </h4>
-                            {context.comment(item)}
+                            {context.commentSummary(item)}
+                            {context.commentTags(item)}
                         </li>
                     ))}
                 </ul>

diff --git a/src/lib/output/themes/default/templates/reflection.tsx b/src/lib/output/themes/default/templates/reflection.tsx
@@ -15,7 +15,10 @@ export function reflectionTemplate(context: DefaultThemeRenderContext, props: Pa
     return (
         <>
             {props.model.hasComment() && (
-                <section class="tsd-panel tsd-comment">{context.comment(props.model)}</section>
+                <section class="tsd-panel tsd-comment">
+                    {context.commentSummary(props.model)}
+                    {context.commentTags(props.model)}
+                </section>
             )}
 
             {props.model instanceof DeclarationReflection &&
@@ -67,7 +70,8 @@ export function reflectionTemplate(context: DefaultThemeRenderContext, props: Pa
                                 <span class="tsd-signature-symbol">]: </span>
                                 {context.type(props.model.indexSignature.type)}
                             </div>
-                            {context.comment(props.model.indexSignature)}
+                            {context.commentSummary(props.model.indexSignature)}
+                            {context.commentTags(props.model.indexSignature)}
                             {props.model.indexSignature?.type instanceof ReflectionType &&
                                 context.parameter(props.model.indexSignature.type.declaration)}
                         </section>

diff --git a/src/lib/utils/component.ts b/src/lib/utils/component.ts
@@ -116,7 +116,7 @@ export abstract class AbstractComponent<O extends ComponentHost>
     private _componentOwner: O;
 
     /**
-     * The name of this component as set by the @Component decorator.
+     * The name of this component as set by the `@Component` decorator.
      */
     public componentName!: string;