diff --git a/docs/source/conf.py b/docs/source/conf.py index 5017f3895..46a3f6bae 100755 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -173,15 +173,6 @@ def autodoc_process_signature( # currently undocumented things logger = getLogger("trio") UNDOCUMENTED = { - "trio.MemorySendChannel", - "trio.MemoryReceiveChannel", - "trio.MemoryChannelStatistics", - "trio.SocketStream.aclose", - "trio.SocketStream.receive_some", - "trio.SocketStream.send_all", - "trio.SocketStream.send_eof", - "trio.SocketStream.wait_send_all_might_not_block", - "trio._subprocess.HasFileno.fileno", "trio.lowlevel.ParkingLot.broken_by", } diff --git a/docs/source/reference-io.rst b/docs/source/reference-io.rst index 665f62dd0..c9170f863 100644 --- a/docs/source/reference-io.rst +++ b/docs/source/reference-io.rst @@ -218,7 +218,6 @@ abstraction. .. autoclass:: SocketStream :members: - :undoc-members: :show-inheritance: .. autoclass:: SocketListener diff --git a/newsfragments/3221.doc.rst b/newsfragments/3221.doc.rst new file mode 100644 index 000000000..31c563cd0 --- /dev/null +++ b/newsfragments/3221.doc.rst @@ -0,0 +1 @@ +Added missing docstrings for public API classes and methods. diff --git a/src/trio/_channel.py b/src/trio/_channel.py index 05037d813..c2cdbfb7c 100644 --- a/src/trio/_channel.py +++ b/src/trio/_channel.py @@ -118,6 +118,12 @@ def __init__(self, max_buffer_size: int | float) -> None: # noqa: PYI041 @attrs.frozen class MemoryChannelStatistics: + """Statistics about a memory channel. + + Returned by :meth:`MemorySendChannel.statistics` and + :meth:`MemoryReceiveChannel.statistics`. + """ + current_buffer_used: int max_buffer_size: int | float open_send_channels: int @@ -152,6 +158,13 @@ def statistics(self) -> MemoryChannelStatistics: @final @attrs.define(eq=False, repr=False, slots=False) class MemorySendChannel(SendChannel[SendType], metaclass=NoPublicConstructor): + """The send end of a memory channel, created by + :func:`open_memory_channel`. + + See :ref:`channels` for details. + + """ + _state: MemoryChannelState[SendType] _closed: bool = False # This is just the tasks waiting on *this* object. As compared to @@ -300,6 +313,13 @@ async def aclose(self) -> None: @final @attrs.define(eq=False, repr=False, slots=False) class MemoryReceiveChannel(ReceiveChannel[ReceiveType], metaclass=NoPublicConstructor): + """The receive end of a memory channel, created by + :func:`open_memory_channel`. + + See :ref:`channels` for details. + + """ + _state: MemoryChannelState[ReceiveType] _closed: bool = False _tasks: set[trio._core._run.Task] = attrs.Factory(set) diff --git a/src/trio/_subprocess.py b/src/trio/_subprocess.py index 145c2de9b..bff4008b5 100644 --- a/src/trio/_subprocess.py +++ b/src/trio/_subprocess.py @@ -98,7 +98,9 @@ def pidfd_open(fd: int, flags: int) -> int: class HasFileno(Protocol): """Represents any file-like object that has a file descriptor.""" - def fileno(self) -> int: ... + def fileno(self) -> int: + """Return the underlying file descriptor as an integer.""" + ... @final diff --git a/src/trio/_tests/_check_type_completeness.json b/src/trio/_tests/_check_type_completeness.json index 6e8c54ea8..c4f86a952 100644 --- a/src/trio/_tests/_check_type_completeness.json +++ b/src/trio/_tests/_check_type_completeness.json @@ -18,20 +18,8 @@ ], "Windows": [], "all": [ - "No docstring found for class \"trio.MemoryReceiveChannel\"", - "No docstring found for class \"trio._channel.MemoryReceiveChannel\"", - "No docstring found for class \"trio.MemoryChannelStatistics\"", - "No docstring found for class \"trio._channel.MemoryChannelStatistics\"", - "No docstring found for class \"trio.MemorySendChannel\"", - "No docstring found for class \"trio._channel.MemorySendChannel\"", "No docstring found for class \"trio._core._run.Task\"", "No docstring found for class \"trio._socket.SocketType\"", - "No docstring found for function \"trio._highlevel_socket.SocketStream.send_all\"", - "No docstring found for function \"trio._highlevel_socket.SocketStream.wait_send_all_might_not_block\"", - "No docstring found for function \"trio._highlevel_socket.SocketStream.send_eof\"", - "No docstring found for function \"trio._highlevel_socket.SocketStream.receive_some\"", - "No docstring found for function \"trio._highlevel_socket.SocketStream.aclose\"", - "No docstring found for function \"trio._subprocess.HasFileno.fileno\"", "No docstring found for class \"trio._sync.AsyncContextManagerMixin\"", "No docstring found for function \"trio._sync._HasAcquireRelease.acquire\"", "No docstring found for function \"trio._sync._HasAcquireRelease.release\"",