[docs] Add XML documentation to hand-written events - #26311
Conversation
Add hand-authored <summary> (and <remarks> where useful) directly above the 38 hand-written 'public event' declarations that were allow-listed as undocumented in tests/cecil-tests/Documentation.KnownFailures.txt. Covers events in AddressBook, AudioToolbox, AVFoundation, CoreFoundation, CoreMidi, CoreServices and ObjCRuntime. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e858bc2-44aa-4fda-adf1-5ad297d1336a
…on allow-list. These 38 hand-written events now have XML documentation, so they no longer need to be allow-listed in the VerifyEveryVisibleMemberIsDocumented test. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e858bc2-44aa-4fda-adf1-5ad297d1336a
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Pull request overview
This PR improves API documentation coverage by adding hand-authored XML documentation to previously-undocumented hand-written public event declarations under src/, and then removing the corresponding allow-listed event entries from the cecil documentation known-failures list.
Changes:
- Added
<summary>/<remarks>XML documentation for multiple hand-written public events across several frameworks (AddressBook, AudioToolbox, AVFoundation, CoreFoundation, CoreMidi, CoreServices, ObjCRuntime). - Removed the now-documented
E:entries for those events fromtests/cecil-tests/Documentation.KnownFailures.txt. - Added additional clarifying
<see cref="..."/>references in new event remarks.
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/cecil-tests/Documentation.KnownFailures.txt | Removes allow-listed undocumented event entries now covered by new XML docs. |
| src/ObjCRuntime/Runtime.cs | Adds XML docs for runtime events related to assembly registration and exception marshaling. |
| src/CoreServices/FSEvents.cs | Adds XML docs for FSEventStream.Events. |
| src/CoreMidi/MidiServices.cs | Adds XML docs for MIDI client/port/endpoint events. |
| src/CoreFoundation/CFStream.cs | Adds XML docs for CFStream lifecycle/data availability events. |
| src/CoreFoundation/CFSocket.cs | Adds XML docs for CFSocket events (accept/connect/data/read/write). |
| src/AVFoundation/Events.cs | Adds XML docs for AVAudioPlayer/AVAudioSession events. |
| src/AudioToolbox/AudioQueue.cs | Adds XML docs for audio queue buffer completion and input completion events. |
| src/AudioToolbox/AudioConverter.cs | Adds XML docs for AudioConverter.InputData. |
| src/AddressBook/ABAddressBook.cs | Adds XML docs for ABAddressBook.ExternalChange. |
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
Address review feedback: CFSocketAcceptEventArgs.SocketHandle is internal, so reference the public RemoteEndPoint property and CreateSocket() method instead of the inaccessible native handle. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 7e858bc2-44aa-4fda-adf1-5ad297d1336a
…hstick # Conflicts: # tests/cecil-tests/Documentation.KnownFailures.txt
✅ 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 |
…subscribe (#26325) The `remove` accessor of `AVAudioSession.InputChannelsChanged` incorrectly added the handler again (`+=`) instead of removing it (`-=`), which could lead to duplicate callbacks and leaks. This was found in a review comment on #26311. A search of the whole `src/` tree confirmed this was the only event accessor with this bug. 🤖 Pull request created by Copilot --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This comment has been minimized.
This comment has been minimized.
🚀 [CI Build #3c4ee86] 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 |
Adds hand-authored XML documentation to the 38 hand-written
public eventdeclarations that were allow-listed as undocumented intests/cecil-tests/Documentation.KnownFailures.txt, and removes those 38E:entries from the allow-list.These events are declared directly in manual C# source under
src/(as opposed to the ~67 bgen-generated events, which are documented separately), so the docs are authored by hand directly above eachpublic eventdeclaration.Frameworks covered:
ABAddressBook.ExternalChangeAudioConverter.InputData,OutputAudioQueue.BufferCompleted,InputAudioQueue.InputCompletedAVAudioPlayer(4 events) andAVAudioSession(7 events)CFSocket(5 events) andCFStream(5 events)MidiClient(7 events),MidiPort.MessageReceived,MidiEndpoint.MessageReceivedFSEventStream.EventsRuntime.AssemblyRegistration,MarshalObjectiveCException,MarshalManagedExceptionAll added documentation is well-formed XML and every
<see cref>resolves.🤖 Pull request created by Copilot