docs: add missing docstrings for public API

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",
 }
 

newsfragments/3221.doc.rst

@@ -0,0 +1 @@
+Added missing docstrings for public API classes and methods.

src/trio/_channel.py

@@ -118,6 +118,22 @@ 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`.
+
+    Attributes:
+        current_buffer_used: The number of items currently buffered in the channel.
+        max_buffer_size: The maximum number of items that can be buffered.
+        open_send_channels: The number of open
+            :class:`MemorySendChannel` endpoints.
+        open_receive_channels: The number of open
+            :class:`MemoryReceiveChannel` endpoints.
+        tasks_waiting_send: The number of tasks waiting to send.
+        tasks_waiting_receive: The number of tasks waiting to receive.
+    """
+
     current_buffer_used: int
     max_buffer_size: int | float
     open_send_channels: int
@@ -152,6 +168,14 @@ 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. This implements the
+    :class:`trio.abc.SendChannel` interface.
+
+    """
+
     _state: MemoryChannelState[SendType]
     _closed: bool = False
     # This is just the tasks waiting on *this* object. As compared to
@@ -300,6 +324,14 @@ 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. This implements the
+    :class:`trio.abc.ReceiveChannel` interface.
+
+    """
+
     _state: MemoryChannelState[ReceiveType]
     _closed: bool = False
     _tasks: set[trio._core._run.Task] = attrs.Factory(set)

src/trio/_core/_parking_lot.py

@@ -152,6 +152,8 @@ class ParkingLot:
     # items
     _parked: OrderedDict[Task, None] = attrs.field(factory=OrderedDict, init=False)
     broken_by: list[Task] = attrs.field(factory=list, init=False)
+    """List of tasks that have broken this parking lot via
+    :meth:`break_lot`. An empty list if the lot has not been broken."""
 
     def __len__(self) -> int:
         """Returns the number of parked tasks."""

src/trio/_highlevel_socket.py

@@ -107,6 +107,7 @@ def __init__(self, socket: SocketType) -> None:
                 self.setsockopt(tsocket.IPPROTO_TCP, tsocket.TCP_NOTSENT_LOWAT, 2**14)
 
     async def send_all(self, data: bytes | bytearray | memoryview) -> None:
+        """See :meth:`trio.abc.SendStream.send_all`."""
         if self.socket.did_shutdown_SHUT_WR:
             raise trio.ClosedResourceError("can't send data after sending EOF")
         with self._send_conflict_detector:
@@ -124,13 +125,15 @@ async def send_all(self, data: bytes | bytearray | memoryview) -> None:
                         total_sent += sent
 
     async def wait_send_all_might_not_block(self) -> None:
+        """See :meth:`trio.abc.SendStream.wait_send_all_might_not_block`."""
         with self._send_conflict_detector:
             if self.socket.fileno() == -1:
                 raise trio.ClosedResourceError
             with _translate_socket_errors_to_stream_errors():
                 await self.socket.wait_writable()
 
     async def send_eof(self) -> None:
+        """See :meth:`trio.abc.HalfCloseableStream.send_eof`."""
         with self._send_conflict_detector:
             await trio.lowlevel.checkpoint()
             # On macOS, calling shutdown a second time raises ENOTCONN, but
@@ -141,6 +144,7 @@ async def send_eof(self) -> None:
                 self.socket.shutdown(tsocket.SHUT_WR)
 
     async def receive_some(self, max_bytes: int | None = None) -> bytes:
+        """See :meth:`trio.abc.ReceiveStream.receive_some`."""
         if max_bytes is None:
             max_bytes = DEFAULT_RECEIVE_SIZE
         if max_bytes < 1:
@@ -149,6 +153,7 @@ async def receive_some(self, max_bytes: int | None = None) -> bytes:
             return await self.socket.recv(max_bytes)
 
     async def aclose(self) -> None:
+        """See :meth:`trio.abc.AsyncResource.aclose`."""
         self.socket.close()
         await trio.lowlevel.checkpoint()
 

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

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\"",