[Repo Assist] improve: add (returns) XmlDoc tag for operation response descriptions (+4 tests, 353→357)

[github-actions]

🤖 This PR was created by Repo Assist, an automated AI assistant.

Summary

Generated operation methods now include a <returns> XML documentation tag when the success response has a description in the OpenAPI schema. Previously, buildXmlDoc emitted <summary>, <remarks>, and <param> tags but silently dropped the response description.

Root cause

XmlDoc.buildXmlDoc in Utils.fs had no returnDoc parameter, so the response description was never surfaced. The okResponse value was also scoped inside the retMimeAndTy binding, making it unavailable to the later XmlDoc builder.

Changes

File	Change
Utils.fs	Extend buildXmlDoc with an optional returnDoc : string option parameter; emit <returns>...</returns> when present
OperationCompiler.fs	Hoist okResponse from inside retMimeAndTy to a top-level binding; derive returnDoc from okResponse.Value.Description and pass it to buildXmlDoc
Schema.XmlDocTests.fs	Add 4 tests: tag present with description, summary preserved alongside returns, no tag when description is blank, no crash with no matching response

Before / After

OpenAPI schema:

/items:
  get:
    summary: List all items
    responses:
      "200":
        description: A list of items
        content: ...

Before: <summary>List all items</summary>
After: <summary>List all items</summary><returns>A list of items</returns>

Trade-offs

None — the change is additive. The returnDoc parameter defaults to None in all other paths, so the XmlDoc is unchanged for operations without a response description.

Test Status

✅ Build succeeded
✅ 357 unit tests pass (was 353; +4 new tests for <returns> tag behaviour)
✅ Fantomas format check passes

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@3de4e604a36b5190a1c7dc4719c7341500ba8a95

[Copilot]

Pull request overview

Adds support for emitting an XML documentation <returns> tag on generated operation methods when the selected “success” OpenAPI response includes a non-blank description. This improves parity between OpenAPI response descriptions and generated client method docs.

Changes:

• Extend XmlDoc.buildXmlDoc to accept a returnDoc and emit <returns>...</returns> when present.
• Refactor OperationCompiler to compute okResponse once, derive returnDoc from okResponse.Value.Description, and pass it through to buildXmlDoc.
• Add tests covering presence/absence of the <returns> tag in method XML doc output.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
src/SwaggerProvider.DesignTime/Utils.fs	Adds returnDoc support to XML doc builder and emits <returns> when non-empty.
src/SwaggerProvider.DesignTime/OperationCompiler.fs	Hoists okResponse and threads response description into method XmlDoc generation.
tests/SwaggerProvider.Tests/Schema.XmlDocTests.fs	Adds new unit tests validating <returns> tag behavior for operation methods.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.