[Repo Assist] improve: enrich XML documentation for generated API methods (#349)

* improve: enrich XML documentation for generated methods with param descriptions and remarks

- Build structured XML doc (<summary>, <remarks>, <param>) instead of plain text
- Add <param name="..."> entries for OpenAPI parameters that have descriptions
- Add <remarks> for operation.Description when it differs from Summary
- Apply same improvement to both v2 (SwaggerClientProvider) and v3 (OpenApiClientProvider)
- XML-escape description text to prevent malformed doc comments
- Resolves the TODO comment that has been in the code since the initial implementation

241 unit tests pass; format check passes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* ci: trigger checks

* refactor: extract shared XML doc generation to Utils.fs

Agent-Logs-Url: https://github.com/fsprojects/SwaggerProvider/sessions/1ebc143c-89b5-4035-8920-2271a97cde2b

Co-authored-by: sergey-tihon <1197905+sergey-tihon@users.noreply.github.com>

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: sergey-tihon <1197905+sergey-tihon@users.noreply.github.com>

Author: 4 people

src/SwaggerProvider.DesignTime/Utils.fs

@@ -332,6 +332,35 @@ module SchemaReader =
                                 resolvedPath
         }
 
+module XmlDoc =
+    open System
+
+    let private escapeXml(s: string) =
+        s.Replace("&", "&amp;").Replace("<", "&lt;").Replace(">", "&gt;")
+
+    /// Builds a structured XML doc string from summary, description, and parameter descriptions.
+    /// paramDescriptions is a sequence of (camelCaseName, description) pairs.
+    let buildXmlDoc (summary: string) (description: string) (paramDescriptions: (string * string) seq) =
+        let summaryPart =
+            if String.IsNullOrEmpty summary then
+                ""
+            else
+                $"<summary>{escapeXml summary}</summary>"
+
+        let remarksPart =
+            if String.IsNullOrEmpty description || description = summary then
+                ""
+            else
+                $"<remarks>{escapeXml description}</remarks>"
+
+        let paramParts =
+            [ for name, desc in paramDescriptions do
+                  if not(String.IsNullOrWhiteSpace desc) then
+                      yield $"<param name=\"{name}\">{escapeXml desc}</param>" ]
+            |> String.concat ""
+
+        summaryPart + remarksPart + paramParts
+
 type UniqueNameGenerator(?occupiedNames: string seq) =
     let hash = System.Collections.Generic.HashSet<_>()
 

src/SwaggerProvider.DesignTime/v2/OperationCompiler.fs

@@ -252,8 +252,14 @@ type OperationCompiler(schema: SwaggerObject, defCompiler: DefinitionCompiler, i
                         | true, None -> (awaitTask responseUnit).Raw
             )
 
-        if not <| String.IsNullOrEmpty(op.Summary) then
-            m.AddXmlDoc(op.Summary) // TODO: Use description of parameters in docs
+        let xmlDoc =
+            let paramDescriptions =
+                [ for p in op.Parameters -> niceCamelName p.Name, p.Description ]
+
+            XmlDoc.buildXmlDoc op.Summary op.Description paramDescriptions
+
+        if not(String.IsNullOrEmpty xmlDoc) then
+            m.AddXmlDoc xmlDoc
 
         if op.Deprecated then
             m.AddObsoleteAttribute("Operation is deprecated", false)

src/SwaggerProvider.DesignTime/v3/OperationCompiler.fs

@@ -96,7 +96,7 @@ type OperationCompiler(schema: OpenApiDocument, defCompiler: DefinitionCompiler,
         let (|NoMediaType|_|)(content: IDictionary<string, OpenApiMediaType>) =
             if isNull content || content.Count = 0 then Some() else None
 
-        let payloadMime, parameters, ctArgIndex =
+        let payloadTy, payloadMime, parameters, ctArgIndex =
             /// handles de-duplicating Swagger parameter names if the same parameter name
             /// appears in multiple locations in a given operation definition.
             let uniqueParamName usedNames (param: IOpenApiParameter) =
@@ -195,7 +195,7 @@ type OperationCompiler(schema: OpenApiDocument, defCompiler: DefinitionCompiler,
 
                 ctArgIndex, requiredProvidedParams @ optionalProvidedParams @ [ ctParam ]
 
-            payloadTy.ToMediaType(), parameters, ctArgIndex
+            payloadTy, payloadTy.ToMediaType(), parameters, ctArgIndex
 
         // find the inner type value
         let retMimeAndTy =
@@ -494,8 +494,16 @@ type OperationCompiler(schema: OpenApiDocument, defCompiler: DefinitionCompiler,
                                 | _ -> Expr.Coerce(<@ RuntimeHelpers.asyncCast t %(awaitTask responseObj) @>, overallReturnType)
             )
 
-        if not <| String.IsNullOrEmpty(operation.Summary) then
-            m.AddXmlDoc(operation.Summary) // TODO: Use description of parameters in docs
+        let xmlDoc =
+            let paramDescriptions =
+                [ for p in openApiParameters -> niceCamelName p.Name, p.Description
+                  if not(isNull operation.RequestBody) then
+                      yield niceCamelName(payloadTy.ToString()), operation.RequestBody.Description ]
+
+            XmlDoc.buildXmlDoc operation.Summary operation.Description paramDescriptions
+
+        if not(String.IsNullOrEmpty xmlDoc) then
+            m.AddXmlDoc xmlDoc
 
         if operation.Deprecated then
             m.AddObsoleteAttribute("Operation is deprecated", false)