From b5ff0ee6fdc8b67a005e8edc0732b626e514e49b Mon Sep 17 00:00:00 2001
From: Jose <jose@zeroc.com>
Date: Wed, 29 Apr 2026 17:29:07 +0200
Subject: [PATCH] Document whitespace-suppression behavior on
 CodeBlock.WriteLine and AddBlock

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.
---
 src/ZeroC.CodeBuilder/CodeBlock.cs | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/ZeroC.CodeBuilder/CodeBlock.cs b/src/ZeroC.CodeBuilder/CodeBlock.cs
index ada9ae4561..2b7ca2f5e5 100644
--- a/src/ZeroC.CodeBuilder/CodeBlock.cs
+++ b/src/ZeroC.CodeBuilder/CodeBlock.cs
@@ -46,6 +46,9 @@ public CodeBlock()
 
     /// <summary>Adds another code block to this one, separated by newlines.</summary>
     /// <param name="block">The block to add.</param>
+    /// <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>
     public void AddBlock(CodeBlock block) => Write($"\n{block}\n");
 
     /// <summary>Creates a new code block with the content indented by 4 spaces.</summary>
@@ -103,5 +106,11 @@ public void Write(string value)
 
     /// <summary>Writes the specified value followed by a newline to the code block.</summary>
     /// <param name="value">The value to write.</param>
+    /// <remarks><see cref="Write"/> drops empty and whitespace-only strings, so <c>WriteLine("")</c>
+    /// and <c>WriteLine("   ")</c> are no-ops. This is intentional: it lets callers interpolate values
+    /// 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>
     public void WriteLine(string value) => Write($"{value}\n");
 }