Generate a returns doc comment for cs::encodedReturn service operations

[bernardnormier]

Fixes #4927.

The service-side declaration of a cs::encodedReturn operation now gets a <returns> doc comment. Its return value
is a PipeReader holding the encoded return value, or a tuple of that reader and the streamed return, so the Slice
@returns tags don't describe it directly:

• Without a streamed return, the comment is the fixed text "The encoded return value."
• With a streamed return, the comment is a tuple list with the Payload element and that fixed text, followed by the
  stream element with its @returns text, or "The streamed return value." when it is not documented.

The "A tuple containing" list formatting is now shared with the existing <returns> comment for tuple returns.

Two documented cs::encodedReturn operations were added to DocumentationTests.slice, and DocumentationTests.cs
checks their generated comments in the XML documentation file. Generated output for the streamed case:

/// <returns>
/// A tuple containing:
/// <list type="bullet">
/// <item><term>Payload</term><description>The encoded return value.</description></item>
/// <item><term>Entries</term><description>The log entries.</description></item>
/// </list>
/// </returns>
[SliceOperation("streamLog", EncodedReturn = true)]
global::System.Threading.Tasks.ValueTask<(global::System.IO.Pipelines.PipeReader Payload, global::System.Collections.Generic.IAsyncEnumerable<string> Entries)> StreamLogAsync(

Follow-up to #4926.

What's Changed

Area: Slice codec

• The Slice compiler now generates a <returns> doc comment for the service-side declaration of operations with the
  cs::encodedReturn attribute.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The new generated documentation lacks automated regression assertions.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds generated <returns> documentation for service operations using cs::encodedReturn.

Changes:

• Documents encoded payloads and streamed return tuples.
• Shares tuple-return documentation formatting.
• Adds encoded-return Slice fixtures.

File summaries

File	Description
ServiceGenerator.cs	Emits encoded-return documentation.
OperationExtensions.cs	Builds encoded and tuple return comments.
DocumentationTests.slice	Adds documentation fixtures.

Review details

• Files reviewed: 3/3 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bernardnormier]

Added XML documentation tests for both operations in 678b20f.

[InsertCreativityHere]

Looks good, but I also agree, the testing here seems lackluster. Just making sure the doc-comment doesn't emit any warnings could let many kinds of failures through silently.

[InsertCreativityHere]

In the case where the user hasn't documented their stream parameter, this will generate a doc-comment describing a tuple of one element, which is better than the current state, but feels incomplete.

Maybe we could add a fallback for when FormatOverview returns null, so we always generate 2 items in the list?

[bernardnormier]

Done in 678b20f: the stream item is always listed, with "The streamed return value." when it has no @returns.

[InsertCreativityHere]

Looks good to me!