docs: add missing docstrings for public API

[nightcityblade]

Fixes #3221

Adds docstrings to the following public API items that were showing up without documentation:

• MemorySendChannel — class docstring referencing open_memory_channel
• MemoryReceiveChannel — class docstring referencing open_memory_channel
• MemoryChannelStatistics — class docstring with attribute descriptions
• SocketStream.send_all, wait_send_all_might_not_block, send_eof, receive_some, aclose — short docstrings referencing the parent ABC methods
• HasFileno.fileno — method docstring
• ParkingLot.broken_by — attribute docstring

The SocketStream method docstrings use See :meth:... cross-references rather than duplicating the ABC documentation, keeping them in sync with the parent class.

Tests run: pytest src/trio/_tests/test_channel.py src/trio/_tests/test_highlevel_socket.py src/trio/_core/_tests/test_parking_lot.py — all pass.

[jakkdl]

See discussion in #3388

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00000%. Comparing base (3dd35d7) to head (54c94dd).
⚠️ Report is 12 commits behind head on main.

Additional details and impacted files

@@               Coverage Diff               @@
##                 main        #3404   +/-   ##
===============================================
  Coverage   100.00000%   100.00000%           
===============================================
  Files             128          128           
  Lines           19424        19418    -6     
  Branches         1318         1318           
===============================================
- Hits            19424        19418    -6     

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% <ø> (ø)

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[A5rocks]

BTW please make CI pass!

[nightcityblade]

Fixed! I've updated the type completeness checklist to remove the entries that are now resolved by the new docstrings. CI should pass now.

[CoolCat467]

Need to update type completeness file, you need to do python src/trio/_tests/check_type_completeness.py --overwrite-file like CI says to.

[nightcityblade]

Thanks @CoolCat467! I ran python src/trio/_tests/check_type_completeness.py --overwrite-file to update the type completeness checklist. CI should pass now.

[nightcityblade]

Thanks for the feedback @A5rocks @CoolCat467! I've rebased on upstream/main and am working on getting the type_completeness check to pass. The docstrings are present at runtime but pyright's --verifytypes isn't picking some of them up — I'll investigate and push a fix.

[jakkdl]

The docstrings are present at runtime but pyright's --verifytypes isn't picking some of them up — I'll investigate and push a fix.

The current CI errors are

1. you (or, well, probably check_type_completeness doing so on your system) adding trio._core._io_kqueue._KqueueStatistics to the json for Darwin. It indeed doesn't have a docstring, so it's weird that check_type_completeness [when run in CI] doesn't pick up on it. You could give it one, or simply manually undo the change to the json for now. The script can be a bit funky
2. you need to update the list in https://github.com/nightcityblade/trio/blob/17438782ac724eec0399115c8da92d79e2e1e8da/docs/source/conf.py#L173-L186
3. add a newsfragment (see newsfragments/README.rst)
4. fix https://app.readthedocs.org/projects/trio/builds/31890097/#311595438--75

[nightcityblade]

Thanks @jakkdl for the detailed feedback! I'll address all four points:

1. Revert the KqueueStatistics json change for now
2. Update the conf.py undocumented list
3. Add a newsfragment (3221.doc.rst)
4. Fix the readthedocs build issue

Will push the fixes shortly.

[CoolCat467]

still have RTD failures

docstring of trio.MemorySendChannel:4: WARNING: undefined label: 'channel' [ref.ref]
docstring of trio.MemoryReceiveChannel:4: WARNING: undefined label: 'channel' [ref.ref]

[nightcityblade]

Fixed the RTD warnings — the docstrings in MemorySendChannel and MemoryReceiveChannel were referencing channel but the label in reference-core.rst is channels (plural).
Updated both references.