diff --git a/tools/api-markdown-documenter/CHANGELOG.md b/tools/api-markdown-documenter/CHANGELOG.md index 47ddd447120c..c5b94e4d87e0 100644 --- a/tools/api-markdown-documenter/CHANGELOG.md +++ b/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`. diff --git a/tools/api-markdown-documenter/README.md b/tools/api-markdown-documenter/README.md index 4a9939939f85..f6aa1ce3c113 100644 --- a/tools/api-markdown-documenter/README.md +++ b/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. diff --git a/tools/api-markdown-documenter/package.json b/tools/api-markdown-documenter/package.json index b89c5896324d..c89f555bcce3 100644 --- a/tools/api-markdown-documenter/package.json +++ b/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": { diff --git a/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts b/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts index d44b25cefd58..3539fa012e8a 100644 --- a/tools/api-markdown-documenter/src/api-item-transforms/TsdocNodeTransforms.ts +++ b/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}. */ diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html index 07fafdcbbc34..c9f2386e2ff2 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/index.html @@ -29,7 +29,7 @@

test-suite-a - Test package + Test package diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html index fb2228d2dcf0..cff6bdd28724 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/default-config/test-suite-a.html @@ -15,7 +15,7 @@

- Test package + Test package

diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html index e045c6ec6be5..a7349c952714 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/index.html @@ -25,7 +25,7 @@

test-suite-a - Test package + Test package diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html index 0f053f6d7fb3..eb85534a2c0f 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/flat-config/test-suite-a.html @@ -11,7 +11,7 @@

- Test package + Test package

diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html index 0037a2e64a79..a0e9e1c9fd06 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/index.html @@ -29,7 +29,7 @@

test-suite-a - Test package + Test package diff --git a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html index 718be8690011..4495b6100c27 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html +++ b/tools/api-markdown-documenter/src/test/snapshots/html/simple-suite-test/sparse-config/test-suite-a.html @@ -10,7 +10,7 @@

- Test package + Test package

diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md index 8c37de65cfa2..2291952e5438 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/index.md +++ b/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) | Test package | +| [test-suite-a](./test-suite-a) | Test package | | [test-suite-b](./test-suite-b) | | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md index 7ad602419aff..46fa71786f4e 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/default-config/test-suite-a.md +++ 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) -Test package +Test package ## Remarks {#test-suite-a-remarks} diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md index d7a292a666cc..b5d15fa03386 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/index.md +++ b/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) | Test package | +| [test-suite-a](docs/test-suite-a) | Test package | | [test-suite-b](docs/test-suite-b) | | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md index aaf6dcf8dc62..7366c338c454 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/flat-config/test-suite-a.md +++ 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) -Test package +Test package # Remarks {#test-suite-a-remarks} diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md index 1774e3b0901b..519e8d9d44cc 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/index.md +++ b/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) | Test package | +| [test-suite-a](docs/test-suite-a) | Test package | | [test-suite-b](docs/test-suite-b) | | diff --git a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md b/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md index f9818fae3535..928ecaac6a6d 100644 --- a/tools/api-markdown-documenter/src/test/snapshots/markdown/simple-suite-test/sparse-config/test-suite-a.md +++ 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 -Test package +Test package ### Remarks {#test-suite-a-remarks}