fix: Preserve @example titles

common/changes/@microsoft/tsdoc/example-block-title_2026-07-29-00-00.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@microsoft/tsdoc",
+      "comment": "Fix round-trip emission of `@example` block titles so the title text is preserved on the tag line, and expose the text on a block's tag line via new `DocBlock.tagLineContent` and `DocBlock.bodyContent` accessors",
+      "type": "minor"
+    }
+  ],
+  "packageName": "@microsoft/tsdoc"
+}

tsdoc/etc/tsdoc.api.md

@@ -9,11 +9,13 @@ export class DocBlock extends DocNode {
     // @internal
     constructor(parameters: IDocBlockParameters | IDocBlockParsedParameters);
     get blockTag(): DocBlockTag;
+    get bodyContent(): DocSection;
     get content(): DocSection;
     // @override (undocumented)
     get kind(): DocNodeKind | string;
     // @override (undocumented)
     protected onGetChildNodes(): ReadonlyArray<DocNode | undefined>;
+    get tagLineContent(): DocParagraph | undefined;
 }
 
 // @public

tsdoc/src/emitters/TSDocEmitter.ts

@@ -104,7 +104,12 @@ export class TSDocEmitter {
 
         if (
           docBlock.blockTag.tagNameWithUpperCase === StandardTags.returns.tagNameWithUpperCase ||
-          docBlock.blockTag.tagNameWithUpperCase === StandardTags.defaultValue.tagNameWithUpperCase
+          docBlock.blockTag.tagNameWithUpperCase === StandardTags.defaultValue.tagNameWithUpperCase ||
+          // An "@example" title is the text on its tag line; attach it to the tag line like "@returns".
+          // Guard on the tag line content actually being present so that an untitled "@example" is not
+          // emitted with a trailing space.
+          (docBlock.blockTag.tagNameWithUpperCase === StandardTags.example.tagNameWithUpperCase &&
+            docBlock.tagLineContent !== undefined)
         ) {
           this._writeContent(' ');
           this._hangingParagraph = true;

tsdoc/src/emitters/__tests__/TSDocEmitter.test.ts

@@ -124,6 +124,152 @@ Object {
 `);
 });
 
+// An example containing a title above a code sample.
+test('02b Round-trip @example title above a code sample', () => {
+  const input: string = `
+/**
+ * @example Adding two numbers
+ * \`\`\`ts
+ * add(1, 2);
+ * \`\`\`
+ */
+`;
+
+  expect(createSnapshot(input)).toMatchInlineSnapshot(`
+Object {
+  "errors": Array [],
+  "output": "
+/**
+ * @example Adding two numbers
+ * \`\`\`ts
+ * add(1, 2);
+ * \`\`\`
+ *
+ */
+",
+}
+`);
+});
+
+// An example whose entire content is on the tag line.
+test('02c Round-trip @example title with no body', () => {
+  const input: string = `
+/**
+ * The CPU architecture.
+ * @example \`"AMD64"\`
+ */
+`;
+
+  expect(createSnapshot(input)).toMatchInlineSnapshot(`
+Object {
+  "errors": Array [],
+  "output": "
+/**
+ * The CPU architecture.
+ *
+ * @example \`\\"AMD64\\"\`
+ */
+",
+}
+`);
+});
+
+// An example with inline markup in the title.
+test('02d Round-trip @example title with inline markup', () => {
+  const input: string = `
+/**
+ * @example Using {@link add} on negative numbers
+ * Body text.
+ */
+`;
+
+  expect(createSnapshot(input)).toMatchInlineSnapshot(`
+Object {
+  "errors": Array [],
+  "output": "
+/**
+ * @example Using {@link add} on negative numbers
+ * Body text.
+ */
+",
+}
+`);
+});
+
+// An example with a modifier tag on the tag line ends the example block.
+test('02e Round-trip @example title followed by a modifier tag', () => {
+  const input: string = `
+/**
+ * @example Adding two numbers @internal
+ * \`\`\`ts
+ * add(1, 2);
+ * \`\`\`
+ */
+`;
+
+  expect(createSnapshot(input)).toMatchInlineSnapshot(`
+Object {
+  "errors": Array [],
+  "output": "
+/**
+ * @example Adding two numbers
+ * \`\`\`ts
+ * add(1, 2);
+ * \`\`\`
+ *
+ * @internal
+ */
+",
+}
+`);
+});
+
+// An example whose content begins on the next line has no title.
+test('02f Round-trip @example with no title', () => {
+  const input: string = `
+/**
+ * @example
+ * An example without a title.
+ */
+`;
+
+  expect(createSnapshot(input)).toMatchInlineSnapshot(`
+Object {
+  "errors": Array [],
+  "output": "
+/**
+ * @example
+ *
+ * An example without a title.
+ */
+",
+}
+`);
+});
+
+// A tag line containing only whitespace must not emit a trailing space after the tag.
+test('02g Round-trip @example with a whitespace-only tag line', () => {
+  const input: string = `
+/**
+ * @example${'   '}
+ * An example without a title.
+ */
+`;
+
+  expect(createSnapshot(input)).toMatchInlineSnapshot(`
+Object {
+  "errors": Array [],
+  "output": "
+/**
+ * @example
+ *
+ * An example without a title.
+ */
+",
+}
+`);
+});
+
 test('03 TSDocEmitter.renderHtmlTag()', () => {
   const configuration: TSDocConfiguration = new TSDocConfiguration();
   const htmlTag: DocHtmlStartTag = new DocHtmlStartTag({

tsdoc/src/nodes/DocBlock.ts

@@ -3,6 +3,8 @@
 
 import { DocNodeKind, DocNode, type IDocNodeParameters, type IDocNodeParsedParameters } from './DocNode';
 import { DocSection } from './DocSection';
+import { DocParagraph } from './DocParagraph';
+import { DocNodeTransforms } from '../transforms/DocNodeTransforms';
 import type { DocBlockTag } from './DocBlockTag';
 
 /**
@@ -56,6 +58,116 @@ export class DocBlock extends DocNode {
     return this._content;
   }
 
+  /**
+   * The rich text that appears on the same line as the block tag, or `undefined` if the tag line has
+   * no content.
+   *
+   * @remarks
+   * This is a derived view over {@link DocBlock.content}: it returns the leading nodes of the first
+   * paragraph, up to (but not including) the first line break, re-wrapped in a synthesized
+   * {@link DocParagraph} with surrounding spaces trimmed.  It is `undefined` when the tag line has no
+   * non-whitespace content (for example when the block's content begins on the next line).
+   *
+   * The tag line content supports the same inline content as any paragraph (for example `{@link}`
+   * tags or code spans).  Because TSDoc inline tags may span multiple lines, an inline tag that opens
+   * on the tag line but closes on a later line is a single node with no intervening line break, so the
+   * tag line content extends across those lines up to where the tag closes.
+   *
+   * Individual tags assign their own meaning to this content.  For example, an `@example` block
+   * interprets its tag line content as the title of the example; a documentation tool may fall back to
+   * numeric indexing when it is `undefined`.
+   *
+   * The underlying nodes are shared with {@link DocBlock.content}; this view does not modify the block.
+   */
+  public get tagLineContent(): DocParagraph | undefined {
+    const contentNodes: ReadonlyArray<DocNode> = this._content.nodes;
+    if (contentNodes.length === 0) {
+      return undefined;
+    }
+
+    const firstNode: DocNode = contentNodes[0];
+    if (firstNode.kind !== DocNodeKind.Paragraph) {
+      return undefined;
+    }
+
+    const paragraphNodes: ReadonlyArray<DocNode> = (firstNode as DocParagraph).nodes;
+    if (paragraphNodes.length === 0 || paragraphNodes[0].kind === DocNodeKind.SoftBreak) {
+      // The block's content begins with a line break, so the tag line has no content.
+      return undefined;
+    }
+
+    const tagLineNodes: DocNode[] = [];
+    for (const node of paragraphNodes) {
+      if (node.kind === DocNodeKind.SoftBreak) {
+        break;
+      }
+      tagLineNodes.push(node);
+    }
+
+    const tagLineParagraph: DocParagraph = new DocParagraph(
+      { configuration: this.configuration },
+      tagLineNodes
+    );
+    const trimmedContent: DocParagraph = DocNodeTransforms.trimSpacesInParagraph(tagLineParagraph);
+
+    // A tag line containing only whitespace has no content.
+    if (trimmedContent.nodes.length === 0) {
+      return undefined;
+    }
+
+    return trimmedContent;
+  }
+
+  /**
+   * The block's {@link DocBlock.content} excluding its {@link DocBlock.tagLineContent}.
+   *
+   * @remarks
+   * This is a derived view over {@link DocBlock.content}: when {@link DocBlock.tagLineContent} is
+   * present, the remainder of the first paragraph (the nodes after the first line break) is re-wrapped
+   * in a synthesized {@link DocParagraph}, followed by the remaining content nodes.  When there is no
+   * tag line content, this returns the full content.
+   *
+   * The underlying nodes are shared with {@link DocBlock.content}; this view does not modify the block.
+   */
+  public get bodyContent(): DocSection {
+    const bodySection: DocSection = new DocSection({ configuration: this.configuration });
+    const contentNodes: ReadonlyArray<DocNode> = this._content.nodes;
+
+    if (this.tagLineContent === undefined) {
+      bodySection.appendNodes(contentNodes);
+      return bodySection;
+    }
+
+    // The tag line content consumed the leading portion of the first paragraph; recover the remainder
+    // that follows its first line break and re-wrap it in a synthesized paragraph.
+    const paragraphNodes: ReadonlyArray<DocNode> = (contentNodes[0] as DocParagraph).nodes;
+    let softBreakIndex: number = -1;
+    for (let i: number = 0; i < paragraphNodes.length; ++i) {
+      if (paragraphNodes[i].kind === DocNodeKind.SoftBreak) {
+        softBreakIndex = i;
+        break;
+      }
+    }
+    if (softBreakIndex >= 0) {
+      // Skip the line breaks that separated the tag line content from the body before re-wrapping the
+      // remainder.
+      let remainderStart: number = softBreakIndex + 1;
+      while (
+        remainderStart < paragraphNodes.length &&
+        paragraphNodes[remainderStart].kind === DocNodeKind.SoftBreak
+      ) {
+        ++remainderStart;
+      }
+      const remainderNodes: ReadonlyArray<DocNode> = paragraphNodes.slice(remainderStart);
+      if (remainderNodes.length > 0) {
+        bodySection.appendNode(new DocParagraph({ configuration: this.configuration }, remainderNodes));
+      }
+    }
+
+    bodySection.appendNodes(contentNodes.slice(1));
+    return bodySection;
+  }
+
   /** @override */
   protected onGetChildNodes(): ReadonlyArray<DocNode | undefined> {
     return [this.blockTag, this._content];