Document whitespace-suppression behavior on CodeBlock#4571
Merged
pepone merged 1 commit intoicerpc:mainfrom Apr 29, 2026
Merged
Document whitespace-suppression behavior on CodeBlock#4571pepone merged 1 commit intoicerpc:mainfrom
pepone merged 1 commit intoicerpc:mainfrom
Conversation
…ddBlock
WriteLine("") and AddBlock(emptyBlock) are intentionally no-ops: it lets
callers interpolate possibly-empty values without producing stray blank
lines (e.g. WriteLine(\$\" {body.Indent()}\") with empty body). Vertical
whitespace in final output is managed by ToString, which collapses runs
of blank lines to at most one.
Adds <remarks> on both methods so the design intent is visible to
callers who might otherwise expect WriteLine("") to emit a blank line.
There was a problem hiding this comment.
Pull request overview
Clarifies ZeroC.CodeBuilder.CodeBlock whitespace-suppression semantics so callers understand when “empty” writes/blocks are ignored and how final vertical whitespace is normalized.
Changes:
- Documented
AddBlockbehavior when adding empty blocks and howToStringnormalizes vertical whitespace. - Documented
WriteLinebehavior for empty/whitespace-only input (no-op viaWrite) and referencedToStringblank-line collapsing.
Comment on lines
+49
to
+51
| /// <remarks>Adding an empty <see cref="CodeBlock"/> has no effect — no phantom blank-line gap is | ||
| /// inserted. The vertical whitespace between non-empty blocks is normalized by <see cref="ToString"/>, | ||
| /// which collapses runs of blank lines to at most one.</remarks> |
There was a problem hiding this comment.
The remark says adding an empty CodeBlock has no effect, but AddBlock will also effectively ignore blocks that contain only whitespace because interpolation calls CodeBlock.ToString(), which trims whitespace-only lines to empty. Consider clarifying that "empty" here includes whitespace-only content (and may differ from IsEmpty).
Suggested change
| /// <remarks>Adding an empty <see cref="CodeBlock"/> has no effect — no phantom blank-line gap is | |
| /// inserted. The vertical whitespace between non-empty blocks is normalized by <see cref="ToString"/>, | |
| /// which collapses runs of blank lines to at most one.</remarks> | |
| /// <remarks>Adding a <see cref="CodeBlock"/> whose rendered content is empty has no effect — no | |
| /// phantom blank-line gap is inserted. This includes blocks that contain only whitespace, because | |
| /// interpolation calls <see cref="ToString"/>, which normalizes such content to empty; this may | |
| /// differ from <see cref="IsEmpty"/>. The vertical whitespace between non-empty blocks is also | |
| /// normalized by <see cref="ToString"/>, which collapses runs of blank lines to at most one.</remarks> |
| /// that may be empty without producing stray blank lines (for example | ||
| /// <c>WriteLine($" {body.Indent()}")</c> when <c>body</c> is empty). Vertical whitespace in the | ||
| /// final output is managed by <see cref="ToString"/>, which collapses runs of blank lines to at | ||
| /// most one.</remarks> |
There was a problem hiding this comment.
The remarks refer to ToString collapsing runs of blank lines, but ToString also trims leading/trailing whitespace (including newlines) from the final output. If callers might rely on leading/trailing blank lines being preserved, it may be worth calling out the Trim behavior explicitly in the docs.
Suggested change
| /// most one.</remarks> | |
| /// most one and trims leading and trailing whitespace, including leading and trailing newlines.</remarks> |
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
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.
Clarify
WriteLineandAddBlockbehavior for empty line, empty block