Add missing docstrings for documented public APIs#3388
Add missing docstrings for documented public APIs#3388veeceey wants to merge 1 commit intopython-trio:mainfrom
Conversation
Addresses python-trio#3221 by adding docstrings to all items that appear in the Sphinx documentation but previously had no docstring: - MemorySendChannel, MemoryReceiveChannel, MemoryChannelStatistics class docstrings - SocketStream.send_all, .receive_some, .send_eof, .wait_send_all_might_not_block, .aclose referencing parent ABCs - HasFileno.fileno docstring - ParkingLot.broken_by attribute docstring Also removes :undoc-members: from the SocketStream autoclass directive since all methods now have docstrings. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3388 +/- ##
===============================================
Coverage 100.00000% 100.00000%
===============================================
Files 128 128
Lines 19414 19415 +1
Branches 1318 1318
===============================================
+ Hits 19414 19415 +1
🚀 New features to boost your workflow:
|
|
Looking at this, as-is I don't think these are very descriptive or useful docstrings. Child classes of ABC classes should not be given docstrings. If you leave them blank but with the same method name, they inherit the docstring of the parent class. This change is removing useful information at runtime saying to look at the parent class. And if I'm not understanding this and that is not the case, then the child classes should have a copy of the parent class docstrings, not just pointers to the parents. Honestly, I feel like purely automated llm pull requests are a waste of time and resources. Sure there are merits to it at times, but it's usually a pretty bad experience. |
|
If |
|
Closing this PR -- the approach isn't quite right as @CoolCat467 pointed out, and I don't want to waste maintainer time. Thanks for the feedback. |
Summary
Addresses #3221 by adding docstrings to all items identified as appearing in the Sphinx documentation without a docstring.
Changes:
MemorySendChannelandMemoryReceiveChannel: Added class-level docstrings describing these as the sending/receiving ends of a memory channel, with cross-references toopen_memory_channeland the channel-mpmc section.MemoryChannelStatistics: Added a class docstring explaining it is the return type of.statistics()and pointing toopen_memory_channelfor field details.SocketStream.send_all,.receive_some,.send_eof,.wait_send_all_might_not_block,.aclose: Added brief docstrings that reference the parent ABC method (e.g. "Seetrio.abc.SendStream.send_all."). Also removed:undoc-members:from theSocketStreamautoclass RST directive since all methods now have docstrings.HasFileno.fileno: Added a one-line docstring.ParkingLot.broken_by: Added an attribute docstring explaining what the list contains and its effect onpark.Includes a
3221.doc.rstnewsfragment.Test plan
🤖 Generated with Claude Code