fix(frontmatter): correctly resolve frontmatterCommentTags for signatures

Author: tgreyuk

.changeset/config.json

@@ -12,7 +12,6 @@
   "updateInternalDependencies": "minor",
   "ignore": [
     "@devtools/*",
-    "typedoc-plugin-frontmatter",
     "typedoc-github-wiki-theme",
     "typedoc-gitlab-wiki-theme",
     "typedoc-vitepress-theme",

.changeset/lazy-bats-stay.md

@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-frontmatter': patch
+---
+
+- Correctly resolve `frontmatterCommentTags` for signatures (#848).

package-lock.json

@@ -31,7 +31,7 @@
   },
   "homepage": "https://typedoc-plugin-markdown.org/plugins/frontmatter",
   "dependencies": {
-    "yaml": "^2.7.0"
+    "yaml": "^2.8.1"
   },
   "peerDependencies": {
     "typedoc-plugin-markdown": ">=4.9.0"

packages/typedoc-plugin-frontmatter/package.json

@@ -0,0 +1,17 @@
+/**
+ * Functionality to map models to comments.
+ *
+ * @module
+ */
+import { Comment, DeclarationReflection, ReflectionKind } from 'typedoc';
+
+export function getComment(model: DeclarationReflection): Comment | undefined {
+  if (
+    model.kind === ReflectionKind.Function &&
+    model.signatures?.length === 1
+  ) {
+    return model.signatures[0].comment;
+  }
+
+  return model.comment;
+}

packages/typedoc-plugin-frontmatter/src/comments.ts

@@ -14,6 +14,7 @@ import {
   MarkdownPageEvent,
 } from 'typedoc-plugin-markdown';
 import * as yaml from 'yaml';
+import { getComment } from './comments.js';
 import { declarations } from './options/index.js';
 import { getResolvedTags } from './tags.js';
 
@@ -28,14 +29,12 @@ export function load(app: MarkdownApplication) {
   app.renderer.on(
     MarkdownPageEvent.BEGIN,
     (page: MarkdownPageEvent<DeclarationReflection>) => {
-      const entryFileName = app.options.getValue('entryFileName') as any;
+      const entryFileName = app.options.getValue('entryFileName') as string;
       const frontmatterGlobals = app.options.getValue('frontmatterGlobals');
       const readmeFrontmatter = app.options.getValue('readmeFrontmatter');
       const indexFrontmatter = app.options.getValue('indexFrontmatter');
-      const resolvedFrontmatterTags = getResolvedTags(
-        app,
-        (page.model as DeclarationReflection)?.comment,
-      );
+      const comment = getComment(page.model);
+      const resolvedFrontmatterTags = getResolvedTags(app, comment);
 
       page.frontmatter = {
         ...(page.frontmatter || {}),

packages/typedoc-plugin-frontmatter/src/index.ts

@@ -0,0 +1,15 @@
+---
+title: someFunction
+layout: blog
+navOrder: 1
+hide: true
+tagOne: Tag value
+---
+
+# Function: someFunction()
+
+> **someFunction**(): `void`
+
+## Returns
+
+`void`

packages/typedoc-plugin-frontmatter/test/__snapshots__/yaml-append-function-frontmatter.snap

@@ -0,0 +1,47 @@
+---
+title: someFunctionWithMultipleSignatures
+layout: blog
+navOrder: 1
+hide: true
+tagOne: Tag value
+---
+
+# Function: someFunctionWithMultipleSignatures()
+
+Comments for greet function
+
+## Call Signature
+
+> **someFunctionWithMultipleSignatures**(`name`): `string`
+
+Comments for overload function A
+
+### Parameters
+
+#### name
+
+`string`
+
+### Returns
+
+`string`
+
+## Call Signature
+
+> **someFunctionWithMultipleSignatures**(`firstName`, `lastName`): `string`
+
+Comments for overload function B
+
+### Parameters
+
+#### firstName
+
+`string`
+
+#### lastName
+
+`string`
+
+### Returns
+
+`string`

packages/typedoc-plugin-frontmatter/test/__snapshots__/yaml-append-function-multiple-signatures-frontmatter.snap

@@ -0,0 +1,52 @@
+---
+title: someFunctionWithMultipleSignatures
+layout: blog
+veryLong: This is a long string that would normally wrap over multiple lines when the text exceeds a certain length.
+navOrder: 1
+hide: true
+tagOne: Tag value
+---
+
+# Function: someFunctionWithMultipleSignatures()
+
+Comments for greet function
+
+## Tag One
+
+Tag value
+
+## Call Signature
+
+> **someFunctionWithMultipleSignatures**(`name`): `string`
+
+Comments for overload function A
+
+### Parameters
+
+#### name
+
+`string`
+
+### Returns
+
+`string`
+
+## Call Signature
+
+> **someFunctionWithMultipleSignatures**(`firstName`, `lastName`): `string`
+
+Comments for overload function B
+
+### Parameters
+
+#### firstName
+
+`string`
+
+#### lastName
+
+`string`
+
+### Returns
+
+`string`

packages/typedoc-plugin-frontmatter/test/__snapshots__/yaml-function-multiple-signatures-tags.snap

@@ -0,0 +1,20 @@
+---
+title: someFunction
+layout: blog
+veryLong: This is a long string that would normally wrap over multiple lines when the text exceeds a certain length.
+navOrder: 1
+hide: true
+tagOne: Tag value
+---
+
+# Function: someFunction()
+
+> **someFunction**(): `void`
+
+## Returns
+
+`void`
+
+## Tag One
+
+Tag value