feat(processor): append @example tags to member description body #5

plugins/theme/helpers/index.mjs

@@ -21,7 +21,7 @@ export default (ctx) => ({
       : "";
 
     const descPart = comment
-      ? ` ${ctx.helpers.getCommentParts(comment.summary ?? comment.content)}`
+      ? ` ${ctx.helpers.getCommentParts(comment.summary ?? comment.content)}${ctx.helpers.renderExamples(comment)}`
       : "";
 
     return `*${namePart}${typePart}${descPart}`;
@@ -64,4 +64,16 @@ export default (ctx) => ({
 
     return null;
   },
+
+  renderExamples(comment) {
+    if (!comment || !comment.blockTags) return "";
+    const examples = comment.blockTags.filter((tag) => tag.tag === "@example");
+    if (!examples.length) return "";
+    return (
+      "\n\n" +
+      examples
+        .map((tag) => ctx.helpers.getCommentParts(tag.content).trim())
+        .join("\n\n")
+    );
+  },
 });

plugins/theme/partials/index.mjs

@@ -27,70 +27,82 @@ export const getMemberPrefix = (model) => {
  * @param {import('typedoc-plugin-markdown').MarkdownThemeContext} ctx
  * @returns {import('typedoc-plugin-markdown').MarkdownThemeContext['partials']}
  */
-export default (ctx) => ({
-  ...ctx.partials,
-  ...typePartials,
+export default (ctx) => {
+  const baseComment = ctx.partials.comment;
 
-  signature(model, options) {
-    const comment = options.multipleSignatures
-      ? model.comment
-      : model.comment || model.parent?.comment;
+  return {
+    ...ctx.partials,
+    ...typePartials,
 
-    const stability = ctx.helpers.stabilityBlockquote(comment);
+    comment(model, options) {
+      return (
+        baseComment.call(ctx, model, { ...options, showTags: false }) +
+        ctx.helpers.renderExamples(model)
+      );
+    },
 
-    return [
-      stability,
-      stability && "",
-      model.typeParameters?.length &&
-        ctx.partials.typeParametersList(model.typeParameters, {
-          headingLevel: options.headingLevel,
-        }),
-      model.parameters?.length &&
-        ctx.partials.parametersList(model.parameters, {
-          headingLevel: options.headingLevel,
-        }),
-      ctx.helpers.typedListItem({
-        label: "Returns",
-        type: model.type ?? "void",
-        comment: model.comment?.getTag("@returns"),
-      }),
-      "",
-      comment &&
-        ctx.partials.comment(comment, {
-          headingLevel: options.headingLevel,
-          showTags: false,
+    signature(model, options) {
+      const comment = options.multipleSignatures
+        ? model.comment
+        : model.comment || model.parent?.comment;
+
+      const stability = ctx.helpers.stabilityBlockquote(comment);
+
+      return [
+        stability,
+        stability && "",
+        model.typeParameters?.length &&
+          ctx.partials.typeParametersList(model.typeParameters, {
+            headingLevel: options.headingLevel,
+          }),
+        model.parameters?.length &&
+          ctx.partials.parametersList(model.parameters, {
+            headingLevel: options.headingLevel,
+          }),
+        ctx.helpers.typedListItem({
+          label: "Returns",
+          type: model.type ?? "void",
+          comment: model.comment?.getTag("@returns"),
         }),
-    ]
-      .filter((x) => typeof x === "string" || Boolean(x))
-      .join("\n");
-  },
+        "",
+        comment &&
+          baseComment.call(ctx, comment, {
+            headingLevel: options.headingLevel,
+            showTags: false,
+          }),
+        ctx.helpers.renderExamples(comment),
+      ]
+        .filter((x) => typeof x === "string" || Boolean(x))
+        .join("\n");
+    },
 
-  memberTitle(model) {
-    const prefix = getMemberPrefix(model);
-    const params = model.signatures?.[0]?.parameters;
+    memberTitle(model) {
+      const prefix = getMemberPrefix(model);
+      const params = model.signatures?.[0]?.parameters;
 
-    if (!params) {
-      return `${prefix}\`${model.name}\``;
-    }
+      if (!params) {
+        return `${prefix}\`${model.name}\``;
+      }
 
-    const paramsString = params
-      .map((param, index) => {
-        const paramName = param.name;
-        if (param.flags?.isOptional) {
-          // For optional params, wrap comma + name in brackets (except for first param)
-          return index === 0 ? `[${paramName}]` : `[, ${paramName}]`;
-        } else {
-          // For required params, add comma separator (except for first param)
-          return index === 0 ? paramName : `, ${paramName}`;
-        }
-      })
-      .join("");
+      const paramsString = params
+        .map((param, index) => {
+          const paramName = param.name;
+          if (param.flags?.isOptional) {
+            // For optional params, wrap comma + name in brackets (except for first param)
+            return index === 0 ? `[${paramName}]` : `[, ${paramName}]`;
+          } else {
+            // For required params, add comma separator (except for first param)
+            return index === 0 ? paramName : `, ${paramName}`;
+          }
+        })
+        .join("");
 
-    return `${prefix}\`${model.name}(${paramsString})\``;
-  },
+      return `${prefix}\`${model.name}(${paramsString})\``;
+    },
 
-  parametersList: ctx.helpers.typedList,
-  typedParametersList: ctx.helpers.typedList,
-  typeDeclarationList: ctx.helpers.typedList,
-  propertiesTable: ctx.helpers.typedList,
-});
+    parametersList: ctx.helpers.typedList,
+    typedParametersList: ctx.helpers.typedList,
+    typeDeclarationList: ctx.helpers.typedList,
+    propertiesTable: ctx.helpers.typedList,
+  };
+};