TSDocEmitter 0.17.0 drops the line break before a code span or {@link}, joining words
Maintainers usually reply within 1 day
Nobody has claimed this yet.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 85/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Active
- Tech stack
- typescript
- Domain
- documentation
Research direction
Start at TrimSpacesTransform.pushAccumulatedText() and run the supplied TSDocEmitter reproduction for code spans, links, and plain text. Done means a soft break before an inline non-text node is preserved without changing the intended handling of breaks between plain words or after inline nodes.
Written by the indexing model from the issue text.
Description
Summary
Since 0.17.0 ("Update emitter to not replace line breaks"), TSDocEmitter drops a soft break that sits immediately before an inline non-text node (code span, {@link}, HTML element), and emits no space in its place. The two words end up joined.
API Extractor 7.59.2 (which moved to @microsoft/tsdoc ~0.17.0) writes this output into the docComment field of .api.json models, so every downstream consumer of the model (documenters, generated indexes) receives the damaged text.
Repro
const t = require("@microsoft/tsdoc");
const cases = {
code: "/**\n * policy is\n * `\"fail\"`.\n */",
link: "/**\n * see the\n * {@link Foo} thing.\n */",
plain: "/**\n * policy is\n * fail now.\n */",
codeMid: "/**\n * a `x`\n * then b.\n */",
};
for (const [k, src] of Object.entries(cases)) {
const sb = new t.StringBuilder();
new t.TSDocEmitter().renderComment(sb, new t.TSDocParser().parseString(src).docComment);
console.log(k, JSON.stringify(sb.toString()));
}
| Case | 0.16.0 | 0.17.0 |
|---|---|---|
| break before code span | policy is `"fail"`. |
policy is`"fail"`. |
break before {@link} |
see the {@link Foo} thing. |
see the{@link Foo} thing. |
| break between plain words | policy is fail now. |
policy is\n * fail now. (preserved, as intended) |
| break after code span | a `x` then b. |
a `x`\n * then b. (preserved, as intended) |
Cause
TrimSpacesTransform.pushAccumulatedText() splits the accumulated text on \n and only emits a DocSoftBreak ahead of a non-empty line. When the accumulated text ends in a soft break ("policy is\n"), the split yields a trailing empty line; it is skipped, and with it the soft break. The default branch then pushes the inline node straight after the text. Before 0.17.0 the soft break was rendered as a space, which masked this.
Suggested fix
In pushAccumulatedText(), when the final line is empty and i !== 0 (the text ended in a line break), still push a DocSoftBreak so the following inline node starts on a new line.
Environment
@microsoft/tsdoc0.17.0 (0.16.0 is correct)@microsoft/api-extractor7.59.2 /@microsoft/api-extractor-model7.33.13- Node 26
- Dominant language
- TypeScript
- Stars
- 5k
- Forks
- 162
- Avg merge
- 17h 4m
- Merged PRs (30d)
- 7
Getting set up
We have not checked this project's setup files yet. Start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from microsoft/tsdoc
-
Difficulty 3/5 1-2 days Newbie friendliness 72/100
Maintainers usually reply within 1 day
-
Difficulty 3/5 1-2 days Newbie friendliness 35/100
microsoft/tsdoc#470 · 2 comments · 6 reactions ·
Maintainers usually reply within 1 day
-
Difficulty 3/5 1-2 days Newbie friendliness 42/100
Maintainers usually reply within 1 day
-
Difficulty 4/5 3-5 days Newbie friendliness 25/100
microsoft/tsdoc#450 · 1 comment ·
Maintainers usually reply within 1 day
-
Difficulty 5/5 Over a week Newbie friendliness 25/100
Maintainers usually reply within 1 day
Similar issues
-
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
supabase/agent-skills#611 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 68/100
polka-codes/test#345 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 1-3 hours Newbie friendliness 92/100
GoogleChromeLabs/project-sesame#217 ·
Maintainers usually reply within 12 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
solana-foundation/solana-com#2202 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 85/100