Repository navigation
fix(generator): keep inline markup when copying XML docs - #433
Merged
Tim-Maes merged 1 commit intoSep 29, 2026
Merged
Conversation
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 < 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>
Owner
|
Hey @JesseKlaasse Thanks, shipping this today! |
This was referenced Oct 12, 2026
This was referenced Oct 26, 2026
This was referenced Nov 2, 2026
This was referenced Nov 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
CopyDocsdrops inline markup from the documentation it copies.FormatXmlDocumentationwritesXElement.Value, which concatenates text nodes only, so:<see cref="..."/>and<see langword="..."/>vanish from the sentence. A source summary likeWhen the primary source (<see cref="ConnectorId"/>) last synced it. <see langword="null"/> when never synced.becomesWhen 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.<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. ButGetDocumentationCommentXml()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/typeparamrefrefers 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:
CopyDocsInlineMarkupTestsruns the generator in a driver withDocumentationMode.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 onmaster(the diagnostics test on the unescapedINV-<n>, CS1570) and pass with the change. Full suite: 985/985.Checklist
dotnet testlocally.🤖 Generated with Claude Code