[api-extractor] `@example` comment title line formatting is not preserved

[Josmithr]

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

[Josmithr]

More generally, it seems like API-Extractor does a fair amount of comment-modification when generating the api.json files. 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]

Discussed on 9/5/2024: The TSDoc standard clearly states that @example allows 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 @returns preserves the text on the same line, because the spec says that @returns is 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]

Pete Gonzalez (@octogonz) I took a stab at implementing this. PR: #476