[bgen] Emit XML documentation for generated events - #26299
Conversation
The binding generator synthesizes 'event' members from the [BaseType] delegate/EventArgs wiring, but emitted no XML documentation for them unless an [EventArgs (..., XmlDocs = ...)] was supplied in the binding. This left 105 generated events undocumented and allow-listed in the documentation known-failures list. Emit a generic <summary> (guarded by BindingTouch.SupportsXmlDocumentation) for both the EventHandler and EventHandler<T> event branches when no explicit XmlDocs are provided. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 42129f24-b8fb-46cc-a816-e6430769fbfb
Add a single-parameter delegate method (DidFinish) to the bgen XmlDocs test's 'xmldocs.cs' so both event branches are exercised: * DidChangeUtteringSpeed (two parameters) covers the generic EventHandler<T> branch. * DidFinish (one parameter) covers the non-generic EventHandler branch. Regenerate the ExpectedXmlDocs.*.xml files, which now include the generated <summary> for both events. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 42129f24-b8fb-46cc-a816-e6430769fbfb
…wn failures. The binding generator now emits XML documentation for the events it synthesizes, so the 67 generated events that were previously allow-listed as undocumented are removed from the documentation known-failures list. The remaining event entries correspond to hand-written (non-generated) events in the manual API surface, which are unaffected by this change. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 42129f24-b8fb-46cc-a816-e6430769fbfb
Keep the original inline 'string.IsNullOrEmpty (xmlDocs)' check so the compiler's flow analysis knows xmlDocs is non-null, instead of using the banned postfix '!' operator. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 42129f24-b8fb-46cc-a816-e6430769fbfb
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Pull request overview
Updates bgen to emit XML documentation for synthesized C# event members generated from delegate/EventArgs wiring, reducing the need for documentation known-failure allow-list entries.
Changes:
- Emit a default generated
<summary>for synthesized events when XML documentation is supported and no[EventArgs (XmlDocs=...)]docs are provided. - Extend the
xmldocsbgen test to exercise both non-generic (EventHandler) and generic (EventHandler<T>) event documentation paths. - Remove now-documented generated events from
tests/cecil-tests/Documentation.KnownFailures.txtand refresh XML doc baselines.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| src/bgen/Generator.cs | Emits default XML <summary> docs for synthesized events (generic and non-generic) when no explicit event XmlDocs are provided. |
| tests/bgen/tests/xmldocs.cs | Adds a single-parameter delegate method to exercise non-generic event doc generation. |
| tests/bgen/tests/ExpectedXmlDocs.iOS.xml | Updates baseline with new synthesized event summaries. |
| tests/bgen/tests/ExpectedXmlDocs.tvOS.xml | Updates baseline with new synthesized event summaries. |
| tests/bgen/tests/ExpectedXmlDocs.macOS.xml | Updates baseline with new synthesized event summaries. |
| tests/bgen/tests/ExpectedXmlDocs.MacCatalyst.xml | Updates baseline with new synthesized event summaries. |
| tests/cecil-tests/Documentation.KnownFailures.txt | Removes generated-event entries that are now documented. |
✅ API diff for current PR / commitNET (empty diffs)✅ API diff vs stableNET (empty diffs)ℹ️ Generator diffGenerator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes) Pipeline on Agent |
🚀 [CI Build #0b836df] Test results 🚀Test results✅ All tests passed on VSTS: test results. 🎉 All 203 tests passed 🎉 Tests counts✅ assembly-processing: All 1 tests passed. Html Report (VSDrops) Download macOS tests✅ Tests on macOS Monterey (12): All 5 tests passed. Html Report (VSDrops) Download Linux Build VerificationPipeline on Agent |
The binding generator synthesizes C#
eventmembers from the[BaseType]delegate/EventArgs wiring, but never emitted any XML documentation for them. As a
result every generated event showed up as an undocumented, publicly-visible member
and had to be allow-listed in the documentation known-failures list.
This PR makes bgen emit a generated
<summary>for each synthesized event (guardedby
BindingTouch.SupportsXmlDocumentation), for both the non-genericEventHandlerand the generic
EventHandler<T>branches. When the binding already provides docsvia
[EventArgs (XmlDocs = ...)], those are used instead and no generated summary isemitted. The generic branch adds a
<see cref=...>to the generated EventArgs type;crefs resolve correctly (verified against the
VerifyNoUnresolvedCrefstest).With the events now documented, 67 generated-event
E:entries are removed fromtests/cecil-tests/Documentation.KnownFailures.txt. The remaining 38E:entries inthat file are hand-written events (not produced by bgen) and are intentionally left
allow-listed; documenting those is a separate follow-up.
Test coverage:
tests/bgen/tests/xmldocs.csgains a single-parameter delegate method(
DidFinish) so both the non-generic and generic event branches are exercised, andthe four
ExpectedXmlDocs.*.xmlbaselines are regenerated accordingly. The bgenXmlDocstest passes on all four platforms.🤖 Pull request created by Copilot