feat(tsdoc): Don't replace line breaks when emitting comments

common/changes/@microsoft/tsdoc/josmithr-dont-strip-line-breaks_2025-10-07-21-19.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "Update emitter to not replace line breaks",
+      "type": "major"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc"
+}

common/config/rush/command-line.json

@@ -4,7 +4,6 @@
  */
 {
   "$schema": "https://developer.microsoft.com/json-schemas/rush/v5/command-line.schema.json",
-
   /**
    * Custom "commands" introduce new verbs for the command-line.  To see the help for these
    * example commands, try "rush --help", "rush my-bulk-command --help", or
@@ -16,7 +15,6 @@
       "name": "build",
       "phases": ["_phase:build"]
     },
-
     {
       "commandKind": "phased",
       "name": "test",
@@ -25,7 +23,6 @@
       "enableParallelism": true,
       "incremental": true
     },
-
     {
       "commandKind": "phased",
       "name": "retest",
@@ -34,14 +31,12 @@
       "enableParallelism": true,
       "incremental": false
     },
-
     {
       "commandKind": "phased",
       "name": "start",
       "summary": "Build all projects, then watch for changes, build and test.",
       "description": "Build all projects, then watches for changes and builds and runs tests for affected projects.",
       "safeForSimultaneousRushProcesses": false,
-
       "enableParallelism": true,
       "incremental": true,
       // Initial execution only uses the build phase so that all dependencies of watch phases have been built
@@ -217,21 +212,16 @@
     //    */
     //   // "autoinstallerName": "my-task"
     // }
-
     {
       "name": "prettier",
       "commandKind": "global",
       "summary": "Used by the pre-commit Git hook. This command invokes Prettier to reformat staged changes.",
-
       "autoinstallerName": "rush-prettier",
-
       // This will invoke common/autoinstall/rush-prettier/node_modules/.bin/pretty-quick
       "shellCommand": "pretty-quick --staged",
-
       "safeForSimultaneousRushProcesses": true
     }
   ],
-
   "phases": [
     {
       "name": "_phase:build",
@@ -250,7 +240,6 @@
       "allowWarningsOnSuccess": false
     }
   ],
-
   /**
    * Custom "parameters" introduce new parameters for specified Rush command-line commands.
    * For example, you might define a "--production" parameter for the "rush build" command.
@@ -475,6 +464,13 @@
       "description": "Perform a production build, including minification optimizations",
       "associatedPhases": ["_phase:build", "_phase:test"],
       "associatedCommands": ["build", "rebuild", "test", "retest"]
+    },
+    {
+      "longName": "--update-snapshots",
+      "parameterKind": "flag",
+      "description": "Update unit test snapshots for all projects",
+      "associatedCommands": ["test", "retest"],
+      "associatedPhases": ["_phase:test"]
     }
   ]
 }

tsdoc/src/__tests__/__snapshots__/DocNodeTransforms.test.ts.snap

@@ -4,9 +4,19 @@ exports[`01 trimSpacesInParagraphNodes() 1`] = `
 Object {
   "kind": "Paragraph",
   "nodes": Array [
+    Object {
+      "kind": "SoftBreak",
+    },
     Object {
       "kind": "PlainText",
-      "nodePlainText": "This is the first ",
+      "nodePlainText": "This is the",
+    },
+    Object {
+      "kind": "SoftBreak",
+    },
+    Object {
+      "kind": "PlainText",
+      "nodePlainText": "first ",
     },
     Object {
       "kind": "InlineTag",
@@ -27,7 +37,21 @@ Object {
     },
     Object {
       "kind": "PlainText",
-      "nodePlainText": "sentence. This is another sentence.",
+      "nodePlainText": "sentence.",
+    },
+    Object {
+      "kind": "SoftBreak",
+    },
+    Object {
+      "kind": "PlainText",
+      "nodePlainText": " This is another",
+    },
+    Object {
+      "kind": "SoftBreak",
+    },
+    Object {
+      "kind": "PlainText",
+      "nodePlainText": "sentence.",
     },
   ],
 }

tsdoc/src/emitters/TSDocEmitter.ts

@@ -313,6 +313,10 @@ export class TSDocEmitter {
         this._renderNodes(docSection.nodes);
         break;
 
+      case DocNodeKind.SoftBreak:
+        this._ensureAtStartOfLine();
+        break;
+
       case DocNodeKind.Paragraph:
         const trimmedParagraph: DocParagraph = DocNodeTransforms.trimSpacesInParagraph(
           docNode as DocParagraph

tsdoc/src/transforms/DocNodeTransforms.ts

@@ -35,16 +35,15 @@ export class DocNodeTransforms {
    *
    * ```
    * nodes: [
-   *   { kind: PlainText, text: "Here are some " },
-   *   { kind: PlainText, text: "words " },
+   *   { kind: PlainText, text: "Here are some" },
+   *   { kind: SoftBreak }
+   *   { kind: PlainText, text: "words" },
+   *   { kind: SoftBreak }
    *   { kind: InlineTag, text: "{\@inheritDoc}" },
    *   { kind: PlainText, text: "to process." }
    * ]
    * ```
    *
-   * Note that in this example, `"words "` is not merged with the preceding node because
-   * its DocPlainText.excerpt cannot span multiple lines.
-   *
    * @param docParagraph - a DocParagraph containing nodes to be transformed
    * @returns The transformed child nodes.
    */

tsdoc/src/transforms/TrimSpacesTransform.ts

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
 // See LICENSE in the project root for license information.
 
-import { DocParagraph, type DocNode, DocNodeKind, DocPlainText } from '../nodes';
+import { DocParagraph, type DocNode, DocNodeKind, DocPlainText, DocSoftBreak } from '../nodes';
 
 /**
  * Implementation of DocNodeTransforms.trimSpacesInParagraphNodes()
@@ -21,6 +21,30 @@ export class TrimSpacesTransform {
     // as soon as nonempty content is encountered.
     let finishedSkippingLeadingSpaces: boolean = false;
 
+    function pushAccumulatedText(): void {
+      const lines: string[] = accumulatedTextChunks.join('').split('\n');
+      for (let i: number = 0; i < lines.length; i++) {
+        const line: string = lines[i];
+        if (line.length !== 0) {
+          if (i !== 0) {
+            transformedNodes.push(
+              new DocSoftBreak({
+                configuration: docParagraph.configuration
+              })
+            );
+          }
+          transformedNodes.push(
+            new DocPlainText({
+              configuration: docParagraph.configuration,
+              text: line
+            })
+          );
+        }
+      }
+      accumulatedTextChunks.length = 0;
+      accumulatedNodes.length = 0;
+    }
+
     for (const node of docParagraph.nodes) {
       switch (node.kind) {
         case DocNodeKind.PlainText:
@@ -53,9 +77,7 @@ export class TrimSpacesTransform {
           }
           break;
         case DocNodeKind.SoftBreak:
-          if (finishedSkippingLeadingSpaces) {
-            pendingSpace = true;
-          }
+          accumulatedTextChunks.push('\n');
           accumulatedNodes.push(node);
           break;
         default:
@@ -68,14 +90,7 @@ export class TrimSpacesTransform {
           if (accumulatedTextChunks.length > 0) {
             // TODO: We should probably track the accumulatedNodes somehow, e.g. so we can map them back to the
             // original excerpts.  But we need a developer scenario before we can design this API.
-            transformedNodes.push(
-              new DocPlainText({
-                configuration: docParagraph.configuration,
-                text: accumulatedTextChunks.join('')
-              })
-            );
-            accumulatedTextChunks.length = 0;
-            accumulatedNodes.length = 0;
+            pushAccumulatedText();
           }
 
           transformedNodes.push(node);
@@ -85,14 +100,7 @@ export class TrimSpacesTransform {
 
     // Push the accumulated text
     if (accumulatedTextChunks.length > 0) {
-      transformedNodes.push(
-        new DocPlainText({
-          configuration: docParagraph.configuration,
-          text: accumulatedTextChunks.join('')
-        })
-      );
-      accumulatedTextChunks.length = 0;
-      accumulatedNodes.length = 0;
+      pushAccumulatedText();
     }
 
     const transformedParagraph: DocParagraph = new DocParagraph({