Skip to content

Conversation

@veeceey
Copy link

@veeceey veeceey commented Feb 10, 2026

Summary

Addresses #3221 by adding docstrings to all items identified as appearing in the Sphinx documentation without a docstring.

Changes:

  • MemorySendChannel and MemoryReceiveChannel: Added class-level docstrings describing these as the sending/receiving ends of a memory channel, with cross-references to open_memory_channel and the channel-mpmc section.
  • MemoryChannelStatistics: Added a class docstring explaining it is the return type of .statistics() and pointing to open_memory_channel for 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. "See trio.abc.SendStream.send_all."). Also removed :undoc-members: from the SocketStream autoclass 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 on park.

Includes a 3221.doc.rst newsfragment.

Test plan

  • Verify the Sphinx docs build correctly and all previously-blank entries now show docstrings
  • Verify the Read the Docs preview renders the new docstrings properly
  • Confirm no existing tests are broken by the changes (all changes are docstring-only)

🤖 Generated with Claude Code

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
Copy link

codecov bot commented Feb 10, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00000%. Comparing base (1ee96c8) to head (01609cc).
⚠️ Report is 2 commits behind head on main.

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     
Files with missing lines Coverage Δ
src/trio/_channel.py 100.00000% <ø> (ø)
src/trio/_core/_parking_lot.py 100.00000% <100.00000%> (ø)
src/trio/_highlevel_socket.py 100.00000% <ø> (ø)
src/trio/_subprocess.py 100.00000% <ø> (ø)
🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@CoolCat467
Copy link
Member

Looking at this, as-is I don't think these are very descriptive or useful docstrings. HasFileno is a protocol for typing purposes and doesn't really need a docstring.

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.

@A5rocks
Copy link
Contributor

A5rocks commented Feb 10, 2026

If HasFileno doesn't matter then we should probably not have autodoc requesting a docstring... I wonder why that's happening. Also, please update the hardcoded list of exemptions from documentation! See https://app.readthedocs.org/projects/trio/builds/31345915/ for that failure.

@veeceey
Copy link
Author

veeceey commented Feb 12, 2026

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.

@veeceey veeceey closed this Feb 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants