Repository navigation
[api-extractor] @example comment title line formatting is not preserved #4860
Description
Per the TSDoc spec, @example comment blocks are intended to treat the first line (the text on the same line as the tag) as the example's "title".
Unfortunately, the formatting information required to differentiate this line from other block contents are not preserved by API-Extractor.
For a TSDoc comment like the following:
/**
* @example Example Title
*
* Example body
*/The expected api.json contents would look like:
"docComment": "/**@example Example Title\n *\n * Example body\n */\n"Instead, what is generated looks like the following:
"docComment": "/**@example\n *\n * Example Title\n *\n * Example body\n */\n"API-Extractor seems to be injecting blank lines between the @example tag and the contents when none are present.
This makes it impossible for consumers of the api.json files from differentiating @example comments with titles from those without titles.
Ideally, API-Extractor would not introduce these blank lines.
A sample repro can be found here: https://github.com/Josmithr/api-extractor-playground/tree/example-comment-bug-repro
Standard questions
Please answer these questions to help us investigate your issue more quickly:
| Question | Answer |
|---|---|
@microsoft/api-extractor version? |
7.47.5 |
| Operating system? | Linux |
| API Extractor scenario? | |
| Would you consider contributing a PR? | Yes |
| TypeScript compiler version? | 5.5.2 |
Node.js version (node -v)? |
20.15.1 |
Activity
Josmithr commentedon Aug 7, 2024
More generally, it seems like API-Extractor does a fair amount of comment-modification when generating the
api.jsonfiles. This seems unnecessary at best, and problematic in cases like this. Would it be a problem to stop tinkering with things like line breaks when transcribing comments?octogonz commentedon Sep 5, 2024
Discussed on 9/5/2024: The TSDoc standard clearly states that
@exampleallows text on the same line, but the TSDoc Playground's "emit" tag normalizes the text to be on the next line, as it does for general block tags. But for example@returnspreserves the text on the same line, because the spec says that@returnsis a special block tag with that feature. Thus, this is likely a bug in the TSDoc parser, not API Extractor. We weren't able to find the exact code responsible, but Joshua Smithrud (@Josmithr) said it is a regression, so he will look at the diff when the wrong behavior was introduced.Fixing the parsing should be easy. (We could actually consider allowing all block tags to accept text on the same line -- I'm open that, but don't remember any context of the design decision, so it might require more discussion.)
Josmithr commentedon Jul 29, 2026
Pete Gonzalez (@octogonz) I took a stab at implementing this. PR: #476