[bgen][docs] Add XML documentation for every Dispose(bool) override - #26301
Conversation
Emit '/// <inheritdoc />' for the bgen-generated 'protected override void Dispose (bool disposing)' method (guarded by BindingTouch.SupportsXmlDocumentation), and add real XML documentation to ObjCRuntime.DisposableObject's Dispose() and Dispose(bool) so the inheritdoc chain resolves to meaningful content. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 05a72201-e64f-4c79-9d23-1e5b344a0b45
…n known failures With bgen emitting '/// <inheritdoc />' for generated Dispose(bool) methods and ObjCRuntime.DisposableObject's Dispose()/Dispose(bool) now documented, the Documentation.VerifyEveryVisibleMemberIsDocumented test no longer needs these 530 entries (529 'Dispose(System.Boolean)' plus DisposableObject.Dispose) as known failures. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 05a72201-e64f-4c79-9d23-1e5b344a0b45
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 XML documentation coverage for the common Dispose (bool disposing) override pattern in generated bindings by having bgen emit /// <inheritdoc /> for generated overrides and by adding real XML docs to ObjCRuntime.DisposableObject so the inheritdoc chain resolves to meaningful content. It also updates the cecil documentation known-failures list to remove entries that should now be documented.
Changes:
- bgen now emits
/// <inheritdoc />for generatedprotected override void Dispose (bool disposing)when XML documentation is enabled. - Added XML documentation for
ObjCRuntime.DisposableObject.Dispose ()andDispose (bool)to provide a solid base for inheritdoc. - Removed now-documented
Dispose(System.Boolean)entries fromtests/cecil-tests/Documentation.KnownFailures.txt.
Reviewed changes
Copilot reviewed 2 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| tests/cecil-tests/Documentation.KnownFailures.txt | Removes Dispose(System.Boolean) entries that should now have XML doc <member> output. |
| src/ObjCRuntime/DisposableObject.cs | Adds base XML docs for Dispose() and Dispose(bool) to make inheritdoc meaningful. |
| src/bgen/Generator.cs | Emits /// <inheritdoc /> for generated Dispose(bool) overrides when XML docs are enabled. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
Address review feedback: 'there'a any [Dispose] attribute' -> 'there are any [Dispose] attributes'. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 05a72201-e64f-4c79-9d23-1e5b344a0b45
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.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
…egram # Conflicts: # tests/cecil-tests/Documentation.KnownFailures.txt
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
✅ 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 |
This comment has been minimized.
This comment has been minimized.
🚀 [CI Build #83d802f] 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 |
Every
protected override void Dispose (bool disposing)in the bindingsnow gets XML documentation, removing ~529 generated entries (plus the base
DisposableObject.Dispose) from the cecil Documentation known-failures list.Changes:
Dispose (bool disposing)now emits/// <inheritdoc />(guarded by
BindingTouch.SupportsXmlDocumentation), so each bound type inheritsthe documentation from its actual base class.
Dispose ()andDispose (bool)so the inheritdoc chain (NativeObject and the manyCoreFoundation/etc. types deriving from it) resolves to meaningful documentation.
Dispose(System.Boolean)(and
DisposableObject.Dispose) entries fromDocumentation.KnownFailures.txt.The ~48 hand-written
Dispose (bool)overrides undersrc/already carried/// <inheritdoc />, so no changes were needed there.Plain
<inheritdoc/>is the correct approach: the cecilVerifyEveryVisibleMemberIsDocumentedtest only requires a<member>entry toexist in the compiler-generated XML, and Roslyn writes
<inheritdoc/>literallyregardless of the base member's doc state. It introduces no crefs, so
VerifyNoUnresolvedCrefsis unaffected.🤖 Pull request created by Copilot