Skip to content

fix: Preserve @example titles - #476

Open
Josmithr wants to merge 2 commits into
microsoft:mainfrom
Josmithr:example-title-preservation
Open

fix: Preserve @example titles#476
Josmithr wants to merge 2 commits into
microsoft:mainfrom
Josmithr:example-title-preservation

Conversation

@Josmithr

@Josmithr Josmithr commented Jul 29, 2026

Copy link
Copy Markdown
Contributor

Summary

Per TSDoc's documented spec, text on the same line as an @example tag is considered the title for the example. The parser previously discarded it. This PR parses the title, exposes it on the AST, and preserves it on round-trip emission.

Round-tripping an @example block would previously result in the title context being lost. It is now preserved.

Input Previous Output
(incorrect line formatting)
New Output
(preserves necessary line formatting)
/**
* Summary.
*
* @example Adding two numbers
* ```ts
* add(1, 2);
* ```
*/
/**
* Summary.
*
* @example
*
* Adding two numbers
* ```ts
* add(1, 2);
* ```
*/
/**
* Summary.
*
* @example Adding two numbers
* ```ts
* add(1, 2);
* ```
*/

Changes

  • New DocExampleBlock node with a title. Registered in DocNodeKind, BuiltInDocNodes, and exported.
  • Parser: @example now captures the same-line text as the title and routes the rest into the content section.
  • Emitter: re-emits the title on the tag line, preserving layout.

Notes

  • Titles are plain-text only for now; inline-tags are not parsed as anything but plain text. The spec is ambiguous about this - support for inline tag parsing could be added if desired.

@Josmithr

Copy link
Copy Markdown
Contributor Author

@octogonz I took a stab at resolving microsoft/rushstack#4860. Would love your feedback when you have a moment.

@Josmithr
Josmithr marked this pull request as ready for review July 30, 2026 00:08
@Josmithr Josmithr changed the title feat: Preserve @example titles fix: Preserve @example titles Jul 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant