improvement(api-markdown-documenter): Updates TSDoc node handling t…

…o emit a warning in place of an error when an embedded `HTML` tag is encountered (microsoft#22688)

We handle such input gracefully, so it really isn't an error. A warning
is still appropriate, however, to ensure the caller is aware of the
situation.

Also updates the logged notice to include the tag that was encountered.

tools/api-markdown-documenter/CHANGELOG.md

@@ -1,5 +1,10 @@
 # @fluid-tools/api-markdown-documenter
 
+## 0.17.1
+
+-   Updates `TSDoc` node handling to emit a _warning_ in place of an _error_ when an embedded `HTML` tag is encountered.
+    Also updates the logged notice to include the tag that was encountered.
+
 ## 0.17.0
 
 -   Updates HTML rendering APIs to operate on `HAST` domain trees from `documentToHtml`, and leverage existing rendering libraries ([hast-util-to-html](https://www.npmjs.com/package/hast-util-to-html) and [hast-util-format](https://www.npmjs.com/package/hast-util-format)) rather than maintaining bespoke rendering code.

tools/api-markdown-documenter/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fluid-tools/api-markdown-documenter",
-	"version": "0.17.0",
+	"version": "0.17.1",
 	"description": "Processes .api.json files generated by API-Extractor and generates Markdown documentation from them.",
 	"homepage": "https://fluidframework.com",
 	"repository": {

tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts

@@ -16,6 +16,8 @@ import {
 	type DocPlainText,
 	type DocSection,
 	type DocInlineTag,
+	type DocHtmlEndTag,
+	type DocHtmlStartTag,
 } from "@microsoft/tsdoc";
 
 import { type Link } from "../Link.js";
@@ -111,11 +113,7 @@ export function _transformTsdocNode(
 		}
 		case DocNodeKind.HtmlStartTag:
 		case DocNodeKind.HtmlEndTag: {
-			// This matches intellisense's policy for HTML in TSDoc/JSDoc comments.
-			options.logger?.error(
-				`Encountered an HTML tag. This library does not support embedded HTML content. Inner contents will be mapped as normal, but the HTML tags will be ignored.`,
-			);
-			return undefined;
+			return transformTsdocHtmlTag(node as DocHtmlStartTag | DocHtmlEndTag, options);
 		}
 		case DocNodeKind.InheritDocTag: {
 			options.logger?.error(
@@ -158,6 +156,31 @@ export function transformTsdocCodeSpan(
 	return CodeSpanNode.createFromPlainText(node.code.trim());
 }
 
+/**
+ * Handler for TSDoc HTML tag nodes.
+ *
+ * @remarks
+ *
+ * This library has made the policy choice to not support embedded HTML content.
+ * Instead, we will emit a warning and ignore the HTML tags (return `undefined`).
+ * "Contained" content (represented as adjacent nodes in the list, appearing between the start and end tag nodes) will
+ * be transformed as normal.
+ *
+ * This matches intellisense's policy for HTML in TSDoc/JSDoc comments.
+ *
+ * We may revisit this in the future.
+ */
+export function transformTsdocHtmlTag(
+	node: DocHtmlStartTag | DocHtmlEndTag,
+	options: TsdocNodeTransformOptions,
+): undefined {
+	const tag = node.emitAsHtml();
+	options.logger?.warning(
+		`Encountered an HTML tag: "${tag}". This library does not support embedded HTML content. Inner contents will be mapped as normal, but the HTML tags will be ignored.`,
+	);
+	return undefined;
+}
+
 /**
  * Converts a {@link @microsoft/tsdoc#DocParagraph} to a {@link ParagraphNode}.
  */