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

src/IceRpc.Slice.Generator/OperationExtensions.cs

@@ -157,12 +157,36 @@ internal CodeBlock BuildEncodeStreamMethod(
             var items = op.ReturnType
                 .Select(r => (r.Name, Overview: DocCommentFormatter.FormatOverview(r.Comment, currentNamespace)))
                 .Where(item => item.Overview is not null)
-                .Select(item => $"<item><term>{item.Name}</term><description>{item.Overview}</description></item>")
+                .Select(item => (item.Name, item.Overview!))
                 .ToList();
 
-            return items.Count > 0
-                ? $"A tuple containing:\n<list type=\"bullet\">\n{string.Join("\n", items)}\n</list>"
-                : null;
+            return items.Count > 0 ? TupleReturnsDocComment(items) : null;
+        }
+
+        /// <summary>Returns the <c>&lt;returns&gt;</c> doc comment for a service operation with
+        /// <c>cs::encodedReturn</c>: a fixed description of the encoded return payload, or for an operation with a
+        /// streamed return, a list with the payload and the streamed return.</summary>
+        internal string GetEncodedReturnsDocComment(string currentNamespace)
+        {
+            const string payloadDescription = "The encoded return value.";
+
+            if (op.StreamedReturn is Field streamReturn)
+            {
+                var items = new List<(string, string)> { (op.EncodedReturnPayloadName, payloadDescription) };
+                if (DocCommentFormatter.FormatOverview(streamReturn.Comment, currentNamespace) is string overview)
+                {
+                    items.Add((streamReturn.Name, overview));
+                }
+                return TupleReturnsDocComment(items);
+            }
+            return payloadDescription;
+        }
+
+        private static string TupleReturnsDocComment(IEnumerable<(string Name, string Description)> items)
+        {
+            IEnumerable<string> listItems = items.Select(
+                item => $"<item><term>{item.Name}</term><description>{item.Description}</description></item>");
+            return $"A tuple containing:\n<list type=\"bullet\">\n{string.Join("\n", listItems)}\n</list>";
         }
 
         /// <summary>Returns the C# return type for an operation (<c>Task</c>, <c>Task&lt;T&gt;</c>, or

src/IceRpc.Slice.Generator/ServiceGenerator.cs

@@ -314,8 +314,11 @@ private static CodeBlock BuildServiceOperationDeclaration(Operation op, string c
         {
             operationBuilder.AddComment("returns", "A value task that completes when this implementation completes.");
         }
-        else if (!op.Attributes.HasAttribute(CSAttributes.CSEncodedReturn) &&
-            op.GetReturnsDocComment(currentNamespace) is string returns)
+        else if (op.Attributes.HasAttribute(CSAttributes.CSEncodedReturn))
+        {
+            operationBuilder.AddComment("returns", op.GetEncodedReturnsDocComment(currentNamespace));
+        }
+        else if (op.GetReturnsDocComment(currentNamespace) is string returns)
         {
             operationBuilder.AddComment("returns", returns);
         }

tests/IceRpc.Slice.Generator.Tests/DocumentationTests.slice

@@ -52,6 +52,17 @@ interface MySessionManager {
 
     /// Retrieves the {@link UserList} containing the names of the active users.
     getActiveUsers() -> UserList
+
+    /// Retrieves the log of the given user.
+    /// @param user: The user.
+    /// @returns: The log entries.
+    [cs::encodedReturn] getLog(user: string) -> Sequence<string>
+
+    /// Streams the log of the given user.
+    /// @param user: The user.
+    /// @returns count: The number of entries.
+    /// @returns entries: The log entries.
+    [cs::encodedReturn] streamLog(user: string) -> (count: int32, entries: stream string)
 }
 
 /// This summary comment includes special XML characters like < > & ' ", which should be properly escaped by