Skip to content

fix(generator): keep inline markup when copying XML docs - #433

Merged
Tim-Maes merged 1 commit into
Tim-Maes:masterfrom
JesseKlaasse:fix/copydocs-keep-inline-xml
Sep 29, 2026
Merged

Tim-Maes merged 1 commit into
Tim-Maes:masterfrom
JesseKlaasse:fix/copydocs-keep-inline-xml

Conversation

@JesseKlaasse

Copy link
Copy Markdown
Contributor

Summary

CopyDocs drops inline markup from the documentation it copies. FormatXmlDocumentation writes XElement.Value, which concatenates text nodes only, so:

  • <see cref="..."/> and <see langword="..."/> vanish from the sentence. A source summary like When the primary source (<see cref="ConnectorId"/>) last synced it. <see langword="null"/> when never synced. becomes When the primary source () last synced it. when never synced. — and that is what Swagger/Scalar then show for every generated DTO.
  • <c> and <para> lose their markup.
  • An escaped &lt; is written back unescaped, which is malformed XML in the generated comment (CS1570 in the consuming project).

This PR copies the element content as XML instead (summary, value, remarks, example, one shared helper instead of four copies).

Why this does not bring back #45. Copying the cref as written (cref="Id") would not bind in a facet that lives in another namespace — that was #45, and flattening to text was the fix. But GetDocumentationCommentXml() already returns every cref in documentation-ID form (P:Domain.Orders.Order.Id, T:Domain.Orders.PaymentKind), and the compiler takes an ID-form cref verbatim instead of binding it. So the crefs survive and a cross-namespace facet still gets no CS1574.

A paramref/typeparamref refers to a parameter of the source member (e.g. a primary-constructor parameter in a record's type summary) that the generated member does not have, so it becomes <c>name</c> rather than a CS1734.

Tests: CopyDocsInlineMarkupTests runs the generator in a driver with DocumentationMode.Diagnose, source type and facet in different namespaces without a using, and asserts the markup is kept and that the compilation has no CS1570/CS1574/CS1580/CS1581/CS1584/CS1658/CS1734/CS1735. All five tests fail on master (the diagnostics test on the unescaped INV-<n>, CS1570) and pass with the change. Full suite: 985/985.

Checklist

  • I read the contributing guide and followed the code of conduct.
  • I added or updated tests when behavior changed.
  • I updated documentation, samples, or release notes when needed. (CHANGELOG, Unreleased → Fixed)
  • I ran dotnet test locally.
  • My change is ready for review.

🤖 Generated with Claude Code

FormatXmlDocumentation copied XElement.Value, which concatenates text nodes only:
<see cref/>, <see langword/> and <paramref/> vanished from the sentence, <c> and <para>
lost their markup, and an escaped &lt; was written back unescaped (CS1570 in the
consuming project). The element content is now copied as XML.

Crefs stay resolvable: Roslyn returns the comment with every cref already in
documentation-ID form (P:Namespace.Type.Member), which the compiler takes verbatim, so a
facet in another namespace than its source still gets no CS1574 (Tim-Maes#45). A paramref or
typeparamref to a parameter the facet does not have becomes <c>name</c>.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@Tim-Maes

Copy link
Copy Markdown
Owner

Hey @JesseKlaasse

Thanks, shipping this today!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants