From c11e1a80a051f04e7cb0fc727eeed161d357b4d5 Mon Sep 17 00:00:00 2001
From: Trevor Burnham <trevorburnham@gmail.com>
Date: Wed, 4 Mar 2026 09:11:42 -0500
Subject: [PATCH] feat(codegen): strip HTML tags from documentation traits in
 generated JSDoc

Adds a DocumentationConverter utility that converts HTML documentation
strings from Smithy @documentation traits into plain text before they
are emitted as JSDoc comments. This makes hover docs in editors (VS Code,
Neovim, etc.) significantly more readable by removing raw HTML tags like
<p>, <a>, <code>, <ul>/<li>, and others.

Fixes aws/aws-sdk-js-v3#6876
---
 .changeset/strip-html-from-docs.md            |   5 +
 .../codegen/DocumentationConverter.java       | 183 ++++++++++++++++++
 .../typescript/codegen/TypeScriptWriter.java  |   2 +
 .../codegen/DocumentationConverterTest.java   | 145 ++++++++++++++
 .../codegen/TypeScriptWriterTest.java         |  18 ++
 5 files changed, 353 insertions(+)
 create mode 100644 .changeset/strip-html-from-docs.md
 create mode 100644 smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/DocumentationConverter.java
 create mode 100644 smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/DocumentationConverterTest.java

diff --git a/.changeset/strip-html-from-docs.md b/.changeset/strip-html-from-docs.md
new file mode 100644
index 00000000000..2ee5f13bfc3
--- /dev/null
+++ b/.changeset/strip-html-from-docs.md
@@ -0,0 +1,5 @@
+---
+"@smithy/service-client-documentation-generator": minor
+---
+
+Strip HTML tags from Smithy documentation traits during TypeScript codegen, producing clean plaintext JSDoc comments instead of raw HTML. This improves hover-doc readability in editors like VS Code and Neovim.
diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/DocumentationConverter.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/DocumentationConverter.java
new file mode 100644
index 00000000000..5c3acebb1ca
--- /dev/null
+++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/DocumentationConverter.java
@@ -0,0 +1,183 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.typescript.codegen;
+
+import java.util.regex.Pattern;
+import software.amazon.smithy.utils.SmithyUnstableApi;
+
+/**
+ * Converts HTML documentation strings from Smithy model {@code @documentation}
+ * traits into plain-text suitable for JSDoc comments.
+ *
+ * <p>The Smithy documentation trait values often contain HTML markup (e.g.
+ * {@code <p>}, {@code <a>}, {@code <code>}, {@code <ul>/<li>}). This class
+ * strips that markup while preserving readable formatting so that IDE hover
+ * docs are clean and legible.
+ */
+@SmithyUnstableApi
+final class DocumentationConverter {
+
+    // Block-level elements that should produce paragraph breaks.
+    private static final Pattern BLOCK_BREAK = Pattern.compile(
+        "<\\s*/?(p|br|h[1-6]|div|section|article|header|footer|nav|aside|main|blockquote|pre|hr|table|thead|tbody|tfoot|tr)\\b[^>]*/?>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // List items get a leading dash for readability.
+    private static final Pattern LIST_ITEM_OPEN = Pattern.compile(
+        "<\\s*li\\b[^>]*>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // Closing list item tags.
+    private static final Pattern LIST_ITEM_CLOSE = Pattern.compile(
+        "<\\s*/li\\s*>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // <ul>, <ol>, <dl> open/close tags — just remove them.
+    private static final Pattern LIST_WRAPPER = Pattern.compile(
+        "<\\s*/?(ul|ol|dl)\\b[^>]*>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // <dt> becomes a newline + bold-ish label, <dd> becomes indented.
+    private static final Pattern DT_TAG = Pattern.compile(
+        "<\\s*dt\\b[^>]*>",
+        Pattern.CASE_INSENSITIVE
+    );
+    private static final Pattern DT_CLOSE = Pattern.compile(
+        "<\\s*/dt\\s*>",
+        Pattern.CASE_INSENSITIVE
+    );
+    private static final Pattern DD_TAG = Pattern.compile(
+        "<\\s*dd\\b[^>]*>",
+        Pattern.CASE_INSENSITIVE
+    );
+    private static final Pattern DD_CLOSE = Pattern.compile(
+        "<\\s*/dd\\s*>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // <code> and <pre> content is wrapped in backticks.
+    private static final Pattern CODE_OPEN = Pattern.compile(
+        "<\\s*(code|pre)\\b[^>]*>",
+        Pattern.CASE_INSENSITIVE
+    );
+    private static final Pattern CODE_CLOSE = Pattern.compile(
+        "<\\s*/(code|pre)\\s*>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // <b>, <strong>, <i>, <em> — just strip them (no markdown equivalent in JSDoc).
+    private static final Pattern INLINE_FORMAT = Pattern.compile(
+        "<\\s*/?(b|strong|i|em|u|s|strike|del|ins|sub|sup|small|big|span|font|mark|abbr|cite|dfn|kbd|samp|var|wbr)\\b[^>]*>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // Anchor tags: extract the link text, drop the URL.
+    private static final Pattern ANCHOR = Pattern.compile(
+        "<\\s*a\\b[^>]*>(.*?)<\\s*/a\\s*>",
+        Pattern.CASE_INSENSITIVE | Pattern.DOTALL
+    );
+
+    // <th> and <td> — separate cells with a tab-like space.
+    private static final Pattern TABLE_CELL = Pattern.compile(
+        "<\\s*/?(th|td)\\b[^>]*>",
+        Pattern.CASE_INSENSITIVE
+    );
+
+    // Any remaining HTML tags.
+    private static final Pattern ANY_TAG = Pattern.compile("<[^>]+>");
+
+    // HTML entities.
+    private static final Pattern ENTITY_AMP = Pattern.compile("&amp;", Pattern.CASE_INSENSITIVE);
+    private static final Pattern ENTITY_LT = Pattern.compile("&lt;", Pattern.CASE_INSENSITIVE);
+    private static final Pattern ENTITY_GT = Pattern.compile("&gt;", Pattern.CASE_INSENSITIVE);
+    private static final Pattern ENTITY_QUOT = Pattern.compile("&quot;", Pattern.CASE_INSENSITIVE);
+    private static final Pattern ENTITY_APOS = Pattern.compile("&#39;|&apos;", Pattern.CASE_INSENSITIVE);
+    private static final Pattern ENTITY_NBSP = Pattern.compile("&nbsp;", Pattern.CASE_INSENSITIVE);
+    private static final Pattern ENTITY_NUMERIC = Pattern.compile("&#(\\d+);");
+    private static final Pattern ENTITY_HEX = Pattern.compile("&#x([0-9a-fA-F]+);");
+
+    // Collapse runs of blank lines into at most two newlines (one blank line).
+    private static final Pattern EXCESS_NEWLINES = Pattern.compile("\\n{3,}");
+    // Collapse runs of spaces/tabs on a single line.
+    private static final Pattern EXCESS_SPACES = Pattern.compile("[ \\t]{2,}");
+    // Trailing whitespace on each line.
+    private static final Pattern TRAILING_WS = Pattern.compile("[ \\t]+$", Pattern.MULTILINE);
+
+    private DocumentationConverter() {}
+
+    /**
+     * Converts an HTML documentation string to plain text suitable for JSDoc.
+     *
+     * @param html the raw HTML documentation value from a Smithy model
+     * @return a plain-text version with HTML tags removed and basic formatting preserved
+     */
+    static String htmlToPlainText(String html) {
+        if (html == null || html.isEmpty()) {
+            return html;
+        }
+
+        String s = html;
+
+        // Anchors — keep link text only.
+        s = ANCHOR.matcher(s).replaceAll("$1");
+
+        // <code>/<pre> → backtick-wrapped.
+        s = CODE_OPEN.matcher(s).replaceAll("`");
+        s = CODE_CLOSE.matcher(s).replaceAll("`");
+
+        // List items → newline + dash.
+        s = LIST_ITEM_OPEN.matcher(s).replaceAll("\n -  ");
+        s = LIST_ITEM_CLOSE.matcher(s).replaceAll("");
+
+        // Definition list elements.
+        s = DT_TAG.matcher(s).replaceAll("\n");
+        s = DT_CLOSE.matcher(s).replaceAll(" - ");
+        s = DD_TAG.matcher(s).replaceAll("   ");
+        s = DD_CLOSE.matcher(s).replaceAll("");
+
+        // List wrappers.
+        s = LIST_WRAPPER.matcher(s).replaceAll("\n");
+
+        // Table cells — add spacing.
+        s = TABLE_CELL.matcher(s).replaceAll("  ");
+
+        // Block-level elements → paragraph break.
+        s = BLOCK_BREAK.matcher(s).replaceAll("\n\n");
+
+        // Inline formatting tags — just remove.
+        s = INLINE_FORMAT.matcher(s).replaceAll("");
+
+        // Any remaining tags.
+        s = ANY_TAG.matcher(s).replaceAll("");
+
+        // Decode HTML entities.
+        s = ENTITY_NBSP.matcher(s).replaceAll(" ");
+        s = ENTITY_LT.matcher(s).replaceAll("<");
+        s = ENTITY_GT.matcher(s).replaceAll(">");
+        s = ENTITY_QUOT.matcher(s).replaceAll("\"");
+        s = ENTITY_APOS.matcher(s).replaceAll("'");
+        s = ENTITY_HEX.matcher(s).replaceAll(mr -> {
+            int codePoint = Integer.parseInt(mr.group(1), 16);
+            return String.valueOf((char) codePoint);
+        });
+        s = ENTITY_NUMERIC.matcher(s).replaceAll(mr -> {
+            int codePoint = Integer.parseInt(mr.group(1));
+            return String.valueOf((char) codePoint);
+        });
+        // &amp; must be last to avoid double-decoding.
+        s = ENTITY_AMP.matcher(s).replaceAll("&");
+
+        // Normalize whitespace.
+        s = TRAILING_WS.matcher(s).replaceAll("");
+        s = EXCESS_SPACES.matcher(s).replaceAll(" ");
+        s = EXCESS_NEWLINES.matcher(s).replaceAll("\n\n");
+
+        return s.trim();
+    }
+}
diff --git a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java
index 62821d19511..712e457bac3 100644
--- a/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java
+++ b/smithy-typescript-codegen/src/main/java/software/amazon/smithy/typescript/codegen/TypeScriptWriter.java
@@ -280,6 +280,7 @@ boolean writeShapeDocs(Shape shape, UnaryOperator<String> preprocessor) {
         if (hasDocumentation || hasDeprecation) {
             String docs =
                 hasDocumentation ? shape.getTrait(DocumentationTrait.class).get().getValue() : "";
+            docs = DocumentationConverter.htmlToPlainText(docs);
             docs = docs.replace("{", "\\{").replace("}", "\\}");
 
             if (hasDeprecation) {
@@ -330,6 +331,7 @@ boolean writeMemberDocs(Model model, MemberShape member) {
         if (hasDocumentation || hasDeprecation) {
             String docs =
                 hasDocumentation ? member.getMemberTrait(model, DocumentationTrait.class).get().getValue() : "";
+            docs = DocumentationConverter.htmlToPlainText(docs);
             docs = docs.replace("{", "\\{").replace("}", "\\}");
 
             if (hasDeprecation) {
diff --git a/smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/DocumentationConverterTest.java b/smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/DocumentationConverterTest.java
new file mode 100644
index 00000000000..fca045b9cbc
--- /dev/null
+++ b/smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/DocumentationConverterTest.java
@@ -0,0 +1,145 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+package software.amazon.smithy.typescript.codegen;
+
+import static org.junit.jupiter.api.Assertions.assertEquals;
+import static org.junit.jupiter.api.Assertions.assertNull;
+import static org.junit.jupiter.api.Assertions.assertTrue;
+
+import org.junit.jupiter.api.Test;
+
+public class DocumentationConverterTest {
+
+    @Test
+    public void returnsNullForNull() {
+        assertNull(DocumentationConverter.htmlToPlainText(null));
+    }
+
+    @Test
+    public void returnsEmptyForEmpty() {
+        assertEquals("", DocumentationConverter.htmlToPlainText(""));
+    }
+
+    @Test
+    public void passesPlainTextThrough() {
+        assertEquals("Hello world.", DocumentationConverter.htmlToPlainText("Hello world."));
+    }
+
+    @Test
+    public void stripsParagraphTags() {
+        String html = "<p>First paragraph.</p><p>Second paragraph.</p>";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("First paragraph.\n\nSecond paragraph.", result);
+    }
+
+    @Test
+    public void stripsAnchorTagsKeepsText() {
+        String html = "See <a href=\"https://example.com\">the docs</a> for details.";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("See the docs for details.", result);
+    }
+
+    @Test
+    public void convertsCodeTagsToBackticks() {
+        String html = "Use the <code>FooClient</code> class.";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("Use the `FooClient` class.", result);
+    }
+
+    @Test
+    public void convertsUnorderedList() {
+        String html = "<p>Options:</p><ul><li>Option A</li><li>Option B</li></ul>";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        // Should have dash-prefixed items.
+        assertTrue(result.startsWith("Options:"), "Should start with 'Options:', got: " + result);
+        assertTrue(result.contains("- Option A"), "Should contain dash-prefixed Option A, got: " + result);
+        assertTrue(result.contains("- Option B"), "Should contain dash-prefixed Option B, got: " + result);
+    }
+
+    @Test
+    public void stripsInlineFormattingTags() {
+        String html = "This is <b>bold</b> and <i>italic</i> and <strong>strong</strong>.";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("This is bold and italic and strong.", result);
+    }
+
+    @Test
+    public void decodesHtmlEntities() {
+        String html = "A &amp; B &lt; C &gt; D &quot;E&quot; F&#39;s";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("A & B < C > D \"E\" F's", result);
+    }
+
+    @Test
+    public void decodesNumericEntities() {
+        String html = "&#169; 2024";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("\u00A9 2024", result);
+    }
+
+    @Test
+    public void decodesHexEntities() {
+        String html = "&#xA9; 2024";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("\u00A9 2024", result);
+    }
+
+    @Test
+    public void handlesBrTags() {
+        String html = "Line one.<br/>Line two.<br>Line three.";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("Line one.\n\nLine two.\n\nLine three.", result);
+    }
+
+    @Test
+    public void collapsesExcessiveWhitespace() {
+        String html = "<p>First.</p>\n\n\n<p>Second.</p>\n\n\n\n<p>Third.</p>";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("First.\n\nSecond.\n\nThird.", result);
+    }
+
+    @Test
+    public void handlesNestedHtml() {
+        String html = "<p>Use <a href=\"https://example.com\"><code>MyApi</code></a> to call the service.</p>";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("Use `MyApi` to call the service.", result);
+    }
+
+    @Test
+    public void handlesDefinitionList() {
+        String html = "<dl><dt>Term</dt><dd>Definition</dd></dl>";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertTrue(result.contains("Term"), "Should contain the term");
+        assertTrue(result.contains("Definition"), "Should contain the definition");
+        assertTrue(result.contains("-"), "Should contain a separator");
+    }
+
+    @Test
+    public void handlesNbsp() {
+        String html = "Hello&nbsp;world";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals("Hello world", result);
+    }
+
+    @Test
+    public void handlesRealWorldEcsExample() {
+        // Simplified version of the ECS RegisterTaskDefinition docs from the issue.
+        String html = "<p>Registers a new task definition from the supplied <code>family</code> and "
+            + "<code>containerDefinitions</code>. Optionally, you can add data volumes to your containers "
+            + "with the <code>volumes</code> parameter. For more information about task definition parameters "
+            + "and defaults, see <a href=\"https://docs.aws.amazon.com/AmazonECS/latest/developerguide/"
+            + "task_defintions.html\">Amazon ECS Task Definitions</a> in the "
+            + "<i>Amazon Elastic Container Service Developer Guide</i>.</p>";
+        String result = DocumentationConverter.htmlToPlainText(html);
+        assertEquals(
+            "Registers a new task definition from the supplied `family` and "
+                + "`containerDefinitions`. Optionally, you can add data volumes to your containers "
+                + "with the `volumes` parameter. For more information about task definition parameters "
+                + "and defaults, see Amazon ECS Task Definitions in the "
+                + "Amazon Elastic Container Service Developer Guide.",
+            result
+        );
+    }
+}
diff --git a/smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/TypeScriptWriterTest.java b/smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/TypeScriptWriterTest.java
index 8425caccbee..f4bf0f67361 100644
--- a/smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/TypeScriptWriterTest.java
+++ b/smithy-typescript-codegen/src/test/java/software/amazon/smithy/typescript/codegen/TypeScriptWriterTest.java
@@ -190,4 +190,22 @@ public void buildDramaticDeprecationAnnotation() {
         String result = TypeScriptWriter.buildDeprecationAnnotation(trait);
         assertEquals("@deprecated Noo!!!", result);
     }
+
+    @Test
+    public void writeShapeDocsStripsHtmlTags() {
+        StringShape shape = StringShape.builder()
+            .id(ShapeId.from("com.example#MyString"))
+            .addTrait(new DocumentationTrait(
+                "<p>Use the <code>FooClient</code> to call <a href=\"https://example.com\">the API</a>.</p>"))
+            .build();
+
+        TypeScriptWriter writer = new TypeScriptWriter("foo");
+        writer.writeShapeDocs(shape);
+        String result = writer.toString();
+
+        assertThat(result, containsString("Use the `FooClient` to call the API."));
+        assertThat(result, not(containsString("<p>")));
+        assertThat(result, not(containsString("<code>")));
+        assertThat(result, not(containsString("<a ")));
+    }
 }