Add SocketStream method docstrings

newsfragments/3221.doc.rst

@@ -0,0 +1 @@
+Add docstrings for ``SocketStream`` methods in the generated API documentation.

src/trio/_highlevel_socket.py

@@ -107,6 +107,10 @@ 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:
+        """Send all of the given data on this socket stream.
+
+        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 +128,21 @@ async def send_all(self, data: bytes | bytearray | memoryview) -> None:
                         total_sent += sent
 
     async def wait_send_all_might_not_block(self) -> None:
+        """Wait until :meth:`send_all` might not block.
+
+        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:
+        """Send an end-of-file indication without closing the receive side.
+
+        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 +153,10 @@ async def send_eof(self) -> None:
                 self.socket.shutdown(tsocket.SHUT_WR)
 
     async def receive_some(self, max_bytes: int | None = None) -> bytes:
+        """Receive up to ``max_bytes`` bytes from this socket stream.
+
+        See :meth:`trio.abc.ReceiveStream.receive_some`.
+        """
         if max_bytes is None:
             max_bytes = DEFAULT_RECEIVE_SIZE
         if max_bytes < 1:
@@ -149,6 +165,7 @@ async def receive_some(self, max_bytes: int | None = None) -> bytes:
             return await self.socket.recv(max_bytes)
 
     async def aclose(self) -> None:
+        """Close this socket stream asynchronously."""
         self.socket.close()
         await trio.lowlevel.checkpoint()
 

src/trio/_tests/_check_type_completeness.json

@@ -20,11 +20,6 @@
     "all": [
         "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\"",