[bgen] Emit XML documentation for generated *EventArgs members - #26304
[bgen] Emit XML documentation for generated *EventArgs members#26304rolfbjarne wants to merge 5 commits into
Conversation
The documentation test (VerifyEveryVisibleMemberIsDocumented) flagged the generated *EventArgs types and their properties as undocumented. Emit XML docs for them: * Notification-based *EventArgs (GenerateEventArgsFile): copy any authored docs from the API definition property, falling back to a generated summary describing the value read from the notification's user info dictionary. * Delegate/event-based *EventArgs (eventArgTypes loop): emit a generated summary for each property (these are derived from method parameters). * DelegateName-generated delegate types named *EventArgs (RenderDelegates): emit a fallback summary when none was copied from the API definition. All doc emission is guarded by BindingTouch.SupportsXmlDocumentation.
…nown-failures. With bgen now emitting XML documentation for the properties of generated *EventArgs classes (both the notification-based and the delegate/event-based ones) and for the DelegateName-generated *EventArgs delegate types, these members are no longer undocumented, so remove their entries from the documentation known-failures allow-list. 469 entries removed (466 generated properties + 3 delegate types). The 15 *EventArgs properties that are hand-written (in partial class files, not generated by bgen) remain in the allow-list since this change does not document them.
… properties In GenerateEventArgsFile()'s notification property loop, the [Field]-branch emitted the `///` doc comment AFTER print_generated_code() (which prints the [BindingImpl] attribute). The C# compiler discards a doc comment that isn't immediately followed by the documented member (CS1587), so these generated properties got no XML documentation entry at all. Move the doc-emission block to before print_generated_code() so the comment attaches to the property. This makes the corresponding removals from Documentation.KnownFailures.txt actually valid. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 164f40b6-1b48-4954-93e9-5eb46b5dc326
Add scenarios to tests/bgen/tests/xmldocs.cs exercising the XML docs bgen now
emits for generated *EventArgs members:
- An undocumented notification EventArgs property (TEventArgs.SomeOtherValue)
to cover the notification [Field]-branch generic fallback summary.
- A value-returning delegate method with [DelegateName ("TShouldMutterEventArgs")]
to cover the RenderDelegates fallback summary emitted for EventArgs-named
DelegateName delegate types.
Regenerate the four ExpectedXmlDocs.<platform>.xml fixtures accordingly.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 164f40b6-1b48-4954-93e9-5eb46b5dc326
This comment has been minimized.
This comment has been minimized.
🔥 Failed to compute test summaries on VSTS: test results 🔥Failed to compute test summaries: |
1 similar comment
🔥 Failed to compute test summaries on VSTS: test results 🔥Failed to compute test summaries: |
This comment has been minimized.
This comment has been minimized.
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
This PR improves the XML documentation emitted by bgen for generated *EventArgs types and members, reducing noise in documentation validation by removing now-resolved known-failure entries.
Changes:
- Emit XML doc comments for generated notification
*EventArgsproperties (including fallback docs when no authored///exists), and fix doc emission ordering in the notification[Field]branch so docs aren’t discarded. - Emit XML doc comments for generated delegate/event
EventArgsproperties (from delegate-method parameters), and add a fallback summary for specificDelegateName-generated delegate types ending inEventArgs. - Update documentation test baselines: remove resolved entries from
Documentation.KnownFailures.txt, extend theXmlDocsbgen test, and regenerateExpectedXmlDocs.*.xmlfixtures.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
src/bgen/Generator.cs |
Adds XML doc emission for generated EventArgs members and a targeted fallback for DelegateName-generated *EventArgs delegate types; fixes doc ordering for notification [Field] branch. |
tests/cecil-tests/Documentation.KnownFailures.txt |
Removes now-documented members/types from the documentation known-failures allow-list. |
tests/bgen/tests/xmldocs.cs |
Adds test coverage for notification [Export] fallback docs and RenderDelegates fallback docs for *EventArgs delegate types. |
tests/bgen/tests/ExpectedXmlDocs.iOS.xml |
Updates expected XML doc output to include new EventArgs member/type docs. |
tests/bgen/tests/ExpectedXmlDocs.tvOS.xml |
Updates expected XML doc output to include new EventArgs member/type docs. |
tests/bgen/tests/ExpectedXmlDocs.macOS.xml |
Updates expected XML doc output to include new EventArgs member/type docs. |
tests/bgen/tests/ExpectedXmlDocs.MacCatalyst.xml |
Updates expected XML doc output to include new EventArgs member/type docs. |
| if (!wroteDelegateDocs && BindingTouch.SupportsXmlDocumentation && shortName.EndsWith ("EventArgs", StringComparison.Ordinal)) | ||
| print ($"/// <summary>A delegate that provides data for the corresponding event.</summary>"); |
This comment has been minimized.
This comment has been minimized.
🔥 [CI Build #87fbea2] Test results 🔥Test results❌ Tests failed on VSTS: test results 30 tests crashed, 0 tests failed, 0 tests passed. Failures❌ assembly-processing tests🔥 Failed catastrophically on VSTS: test results - assembly-processing (no summary found). Html Report (VSDrops) Download ❌ cecil tests🔥 Failed catastrophically on VSTS: test results - cecil (no summary found). Html Report (VSDrops) Download ❌ dotnettests tests (iOS)🔥 Failed catastrophically on VSTS: test results - dotnettests_ios (no summary found). Html Report (VSDrops) Download ❌ dotnettests tests (MacCatalyst)🔥 Failed catastrophically on VSTS: test results - dotnettests_maccatalyst (no summary found). Html Report (VSDrops) Download ❌ dotnettests tests (macOS)🔥 Failed catastrophically on VSTS: test results - dotnettests_macos (no summary found). Html Report (VSDrops) Download ❌ dotnettests tests (Multiple platforms)🔥 Failed catastrophically on VSTS: test results - dotnettests_multiple (no summary found). Html Report (VSDrops) Download ❌ dotnettests tests (tvOS)🔥 Failed catastrophically on VSTS: test results - dotnettests_tvos (no summary found). Html Report (VSDrops) Download ❌ framework tests🔥 Failed catastrophically on VSTS: test results - framework (no summary found). Html Report (VSDrops) Download ❌ fsharp tests🔥 Failed catastrophically on VSTS: test results - fsharp (no summary found). Html Report (VSDrops) Download ❌ generator tests🔥 Failed catastrophically on VSTS: test results - generator (no summary found). Html Report (VSDrops) Download ❌ interdependent-binding-projects tests🔥 Failed catastrophically on VSTS: test results - interdependent-binding-projects (no summary found). Html Report (VSDrops) Download ❌ introspection tests🔥 Failed catastrophically on VSTS: test results - introspection (no summary found). Html Report (VSDrops) Download ❌ linker tests (iOS)🔥 Failed catastrophically on VSTS: test results - linker_ios (no summary found). Html Report (VSDrops) Download ❌ linker tests (MacCatalyst)🔥 Failed catastrophically on VSTS: test results - linker_maccatalyst (no summary found). Html Report (VSDrops) Download ❌ linker tests (macOS)🔥 Failed catastrophically on VSTS: test results - linker_macos (no summary found). Html Report (VSDrops) Download ❌ linker tests (tvOS)🔥 Failed catastrophically on VSTS: test results - linker_tvos (no summary found). Html Report (VSDrops) Download ❌ monotouch tests (iOS)🔥 Failed catastrophically on VSTS: test results - monotouch_ios (no summary found). Html Report (VSDrops) Download ❌ monotouch tests (MacCatalyst)🔥 Failed catastrophically on VSTS: test results - monotouch_maccatalyst (no summary found). Html Report (VSDrops) Download ❌ monotouch tests (macOS)🔥 Failed catastrophically on VSTS: test results - monotouch_macos (no summary found). Html Report (VSDrops) Download ❌ monotouch tests (tvOS)🔥 Failed catastrophically on VSTS: test results - monotouch_tvos (no summary found). Html Report (VSDrops) Download ❌ msbuild tests🔥 Failed catastrophically on VSTS: test results - msbuild (no summary found). Html Report (VSDrops) Download ❌ sharpie tests🔥 Failed catastrophically on VSTS: test results - sharpie (no summary found). Html Report (VSDrops) Download ❌ windows tests🔥 Failed catastrophically on VSTS: test results - windows (no summary found). Html Report (VSDrops) Download ❌ xcframework tests🔥 Failed catastrophically on VSTS: test results - xcframework (no summary found). Html Report (VSDrops) Download ❌ xtro tests🔥 Failed catastrophically on VSTS: test results - xtro (no summary found). Html Report (VSDrops) Download ❌ Tests on macOS Monterey (12) testsHtml Report (VSDrops) Download ❌ Tests on macOS Ventura (13) testsHtml Report (VSDrops) Download ❌ Tests on macOS Sonoma (14) testsHtml Report (VSDrops) Download ❌ Tests on macOS Sequoia (15) testsHtml Report (VSDrops) Download ❌ Tests on macOS Tahoe (26) testsHtml Report (VSDrops) Download SuccessesmacOS testsLinux Build VerificationPipeline on Agent |
🔥 [PR Build #87fbea2] Build failed (Detect API changes) 🔥Build failed for the job 'Detect API changes' (with job status 'Failed') Pipeline on Agent |
|
🔥 Unable to find the contents for the comment: D:\a\1\s\change-detection\results\gh-comment.md does not exist :fire Pipeline on Agent |
🔥 [PR Build #87fbea2] Build failed (Build packages) 🔥Build failed for the job 'Build packages' (with job status 'Failed') Pipeline on Agent |
Resolve conflicts in the bgen XmlDocs test fixtures and the documentation
known-failures allow-list, caused by sibling changes landing on main that
touch the same files:
- tests/bgen/tests/xmldocs.cs: keep both this branch's ShouldMutter
([DelegateName]) scenario and main's DidFinish scenario.
- tests/bgen/tests/ExpectedXmlDocs.{iOS,macOS,MacCatalyst,tvOS}.xml:
regenerated with bgen (iOS/macOS/MacCatalyst via the installed 26.2
runtime packs; tvOS spliced identically since the affected types are not
platform-gated) so the fixtures contain the union of both branches'
generated members in bgen's actual emission order.
- tests/cecil-tests/Documentation.KnownFailures.txt: union of both branches'
removals (469 EventArgs entries from this branch + 253 from main),
computed as the intersection of the two sides' retained entries.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 164f40b6-1b48-4954-93e9-5eb46b5dc326
Make bgen emit XML documentation for the generated
*EventArgsclasses andtheir properties, and remove the corresponding entries from the documentation
known-failures allow-list.
The undocumented
*EventArgsproperty failures came from two bgen generators:GenerateEventArgsFile(),: NSNotificationEventArgs,properties from userinfo keys) — both the string-constant and
[Field]printbranches. Each property now copies any authored
///doc viaWriteDocumentation, falling back to a generic user-info-key summary.property gets a generated summary.
The three
T:...EventArgstype failures were not EventArgs classes at all butDelegateName-generated delegate types whose docs were only written when thedeclaring type is a delegate subclass (false for
DelegateName).RenderDelegatesnow emits a fallback summary, scoped to delegate short names ending in
EventArgsso only those three delegate types are affected.Also fixes a doc-ordering bug in the notification
[Field]branch: the///comment was emitted after
print_generated_code()(which prints the[BindingImpl]attribute), so the compiler discarded it (CS1587) and theproperty got no
<member>entry. The doc block now precedes the generatedattributes.
Removes 469 now-documented entries from
tests/cecil-tests/Documentation.KnownFailures.txt(466 generated properties +3 delegate types), keeping the hand-written properties on partial
*EventArgsclasses (which bgen does not generate) in the allow-list.
Adds coverage to the bgen
XmlDocstest (tests/bgen/tests/xmldocs.cs) for thenotification
[Field]-branch fallback and theRenderDelegatesEventArgsdelegate-type fallback, and regenerates the four
ExpectedXmlDocs.*.xmlfixtures.🤖 Pull request created by Copilot