Repository navigation
[tsdoc] Preserve line breaks before inline nodes in TSDocEmitter - #494
Merged
Ian Clanton-Thuon (iclanton) merged 1 commit intoSep 29, 2026
Merged
Conversation
Since 0.17.0, TrimSpacesTransform dropped a soft break that immediately
preceded an inline node such as a code span, {@link} tag, or HTML element.
pushAccumulatedText() only emitted a DocSoftBreak ahead of a nonempty line,
so text ending in a line break lost it and was joined to the following node
(e.g. "policy is`fail`").
Emit the trailing soft break when the accumulated text is flushed ahead of
an inline node. The trailing break at the end of a paragraph is still
discarded, so the output of trimSpacesInParagraph() is otherwise unchanged.
Fixes microsoft#493
Signed-off-by: C. Spencer Beggs <spencer@beggs.codes>
Ian Clanton-Thuon (iclanton)
approved these changes
Sep 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fixes #493.
Since 0.17.0,
TSDocEmitterdrops a line break that comes immediately before an inline node (code span,{@link}tag, HTML element) and puts no space in its place, so the adjacent words are joined:policy is⏎`"fail"`.policy is`"fail"`.policy is⏎`"fail"`.see the⏎{@link Foo} thing.see the{@link Foo} thing.see the⏎{@link Foo} thing.{@link Foo}⏎``x`` end.{@link Foo}`x` end.{@link Foo}⏎`x` end.API Extractor writes this output to the
docCommentfield of.api.json, so the damaged text reaches every downstream consumer of the model.Cause
TrimSpacesTransform.pushAccumulatedText()splits the accumulated text on\nand emits aDocSoftBreakonly before a nonempty line. When the text ends in a soft break ("policy is\n"), the trailing empty line is skipped, and the soft break goes with it. The inline node is then pushed directly after the text. Before #443, soft breaks were emitted as spaces, which hid the problem.Fix
pushAccumulatedText()now takes afollowedByInlineNodeflag. When the text is flushed before an inline node and ends with a line break, the trailingDocSoftBreakis kept. When the text is flushed at the end of a paragraph, the trailing break is still dropped as before, soDocNodeTransforms.trimSpacesInParagraph()returns the same result in every other case. The existingDocNodeTransformssnapshot does not change.Testing
05 Emit soft breaks before inline nodestoTSDocEmitter.test.ts. It covers a line break before a code span, a{@link}tag, an HTML element, and between two inline nodes. It also covers the two cases that already worked (a break between plain words and a break after a code span) so they stay fixed. The test fails onmainand passes with this change.rush build --to @microsoft/tsdoc: all 17 test suites pass.patchchange file for@microsoft/tsdoc.Signed-off-by: C. Spencer Beggs spencer@beggs.codes