improvement(api-markdown-documenter): Remove embedded html support (m…

…icrosoft#22671)

Support for embedded HTML contents in TSDoc comments has been removed.

The TSDoc parser has some half-baked support for preserving HTML tags in
its output, despite the TSDoc spec making no claims about supporting
embedded HTML. But it does so in a structure that is difficult to handle
correctly, assuming that the output language can support arbitrary HTML
contents, and that it is safe to output the contents raw and
unsanitized.

As a result, this library's support for such contents was similarly
half-baked, and difficult to maintain.

VSCode Intellisense, as a comparison, chooses to completely ignore HTML
tags, and simply render the inner contents ignoring any HTML decorators.

This library has adopted the same policy.

### Breaking Change

If you depended on HTML content preservation, this change will affect
your output.

tools/api-markdown-documenter/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @fluid-tools/api-markdown-documenter
 
+## 0.17.0
+
+### ⚠ BREAKING CHANGES
+
+-   Support for embedded HTML contents in TSDoc comments has been removed.
+    The TSDoc parser has some half-baked support for preserving HTML tags in its output, despite the TSDoc spec making no claims about supporting embedded HTML.
+    But it does so in a structure that is difficult to handle correctly, assuming that the output language can support arbitrary HTML contents, and that it is safe to output the contents raw and unsanitized.
+    As a result, this library's support for such contents was similarly half-baked, and difficult to maintain.
+    VSCode Intellisense, as a comparison, chooses to completely ignore HTML tags, and simply render the inner contents ignoring any HTML decorators.
+    This library has adopted the same policy.
+    If you depended on HTML content preservation, this change will break you.
+
 ## 0.16.1
 
 -   Promote `toHtml` transformation functions to `@public`.

tools/api-markdown-documenter/README.md

@@ -109,6 +109,16 @@ The input `ApiModel` here will generally be the output of [API-Extractor][].
 
 See [Documentation Domain](#documentation-domain) below for more details on the output format.
 
+##### Limitations
+
+###### Embedded HTML
+
+Note: `TSDoc`'s parser has limited support for preserving `HTML` tags in `TSDoc` comments.
+This library does not preserve embedded `HTML` in doc comments.
+Instead, any `HTML` tags found will be discarded, and the contents within will be rendered normally.
+This matches VSCode Intellisense's behavior.
+We may reconsider this in the future.
+
 #### MarkdownRenderer
 
 The `MarkdownRenderer` namespace includes a few functions for generating Markdown contents.

tools/api-markdown-documenter/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fluid-tools/api-markdown-documenter",
-	"version": "0.16.1",
+	"version": "0.17.0",
 	"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

@@ -9,8 +9,6 @@ import {
 	type DocDeclarationReference,
 	type DocEscapedText,
 	type DocFencedCode,
-	type DocHtmlEndTag,
-	type DocHtmlStartTag,
 	type DocLinkTag,
 	type DocNode,
 	DocNodeKind,
@@ -111,11 +109,13 @@ export function _transformTsdocNode(
 		case DocNodeKind.FencedCode: {
 			return transformTsdocFencedCode(node as DocFencedCode, options);
 		}
-		case DocNodeKind.HtmlStartTag: {
-			return transformTsdocHtmlTag(node as DocHtmlStartTag, options);
-		}
+		case DocNodeKind.HtmlStartTag:
 		case DocNodeKind.HtmlEndTag: {
-			return transformTsdocHtmlTag(node as DocHtmlEndTag, options);
+			// 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;
 		}
 		case DocNodeKind.InheritDocTag: {
 			options.logger?.error(
@@ -205,19 +205,6 @@ export function transformTsdocEscapedText(
 	return new PlainTextNode(node.encodedText, /* escaped: */ true);
 }
 
-/**
- * Converts a {@link @microsoft/tsdoc#DocHtmlStartTag} | {@link @microsoft/tsdoc#DocHtmlEndTag} to a {@link PlainTextNode}.
- */
-export function transformTsdocHtmlTag(
-	node: DocHtmlStartTag | DocHtmlEndTag,
-	options: TsdocNodeTransformOptions,
-): PlainTextNode {
-	// TODO: this really isn't right. Mapping this forward as plain text assumes that any output format can support embedded HTML.
-	// That is valid for HTML and Markdown, but not necessarily for other formats.
-	// Instead, we should map embedded HTML content forward in an encapsulated format, and let the renderer decide how to handle it.
-	return new PlainTextNode(node.emitAsHtml(), /* escaped: */ true);
-}
-
 /**
  * Converts a {@link @microsoft/tsdoc#DocPlainText} to a {@link PlainTextNode}.
  */

tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html

@@ -29,7 +29,7 @@ <h2>
                 <a href='./test-suite-a'>test-suite-a</a>
               </td>
               <td>
-                <b>Test package</b>
+                Test package
               </td>
             </tr>
             <tr>

tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html

@@ -15,7 +15,7 @@ <h1>
       </section>
       <section>
         <p>
-          <b>Test package</b>
+          Test package
         </p>
       </section>
       <section>

tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html

@@ -25,7 +25,7 @@ <h1>
               <a href='docs/test-suite-a'>test-suite-a</a>
             </td>
             <td>
-              <b>Test package</b>
+              Test package
             </td>
           </tr>
           <tr>

tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html

@@ -11,7 +11,7 @@
     </section>
     <section>
       <p>
-        <b>Test package</b>
+        Test package
       </p>
     </section>
     <section>

tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html

@@ -29,7 +29,7 @@ <h3>
                 <a href='docs/test-suite-a'>test-suite-a</a>
               </td>
               <td>
-                <b>Test package</b>
+                Test package
               </td>
             </tr>
             <tr>

tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html

@@ -10,7 +10,7 @@ <h2>
       </h2>
       <section>
         <p>
-          <b>Test package</b>
+          Test package
         </p>
       </section>
       <section>

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md

@@ -4,5 +4,5 @@
 
 | Package | Description |
 | --- | --- |
-| [test-suite-a](./test-suite-a) | <b>Test package</b> |
+| [test-suite-a](./test-suite-a) | Test package |
 | [test-suite-b](./test-suite-b) |  |

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md

@@ -2,7 +2,7 @@
 
 [Packages](./) > [test-suite-a](./test-suite-a)
 
-<b>Test package</b>
+Test package
 
 ## Remarks {#test-suite-a-remarks}
 

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md

@@ -2,5 +2,5 @@
 
 | Package | Description |
 | --- | --- |
-| [test-suite-a](docs/test-suite-a) | <b>Test package</b> |
+| [test-suite-a](docs/test-suite-a) | Test package |
 | [test-suite-b](docs/test-suite-b) |  |

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md

@@ -1,6 +1,6 @@
 [Packages](docs/) > [test-suite-a](docs/test-suite-a)
 
-<b>Test package</b>
+Test package
 
 # Remarks {#test-suite-a-remarks}
 

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md

@@ -4,5 +4,5 @@
 
 | Package | Description |
 | --- | --- |
-| [test-suite-a](docs/test-suite-a) | <b>Test package</b> |
+| [test-suite-a](docs/test-suite-a) | Test package |
 | [test-suite-b](docs/test-suite-b) |  |

tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md

@@ -1,6 +1,6 @@
 ## test-suite-a
 
-<b>Test package</b>
+Test package
 
 ### Remarks {#test-suite-a-remarks}