Add documentation for statistics() and aclose() on memory channels (#3101)

* Add documentation to document members

* Clean up copy-paste

* Mark new pyright checktypes error

Author: A5rocks

docs/source/reference-core.rst

@@ -1241,6 +1241,8 @@ more features beyond the core channel interface:
 .. autoclass:: MemoryReceiveChannel
    :members:
 
+.. autoclass:: MemoryChannelStatistics
+   :members:
 
 A simple channel example
 ++++++++++++++++++++++++

newsfragments/3101.doc.rst

@@ -0,0 +1 @@
+Add docstrings for memory channels' ``statistics()`` and ``aclose`` methods.

src/trio/__init__.py

@@ -25,6 +25,7 @@
 # Submodules imported by default
 from . import abc, from_thread, lowlevel, socket, to_thread
 from ._channel import (
+    MemoryChannelStatistics as MemoryChannelStatistics,
     MemoryReceiveChannel as MemoryReceiveChannel,
     MemorySendChannel as MemorySendChannel,
     open_memory_channel as open_memory_channel,

src/trio/_channel.py

@@ -111,7 +111,7 @@ def __init__(self, max_buffer_size: int | float):  # noqa: PYI041
 
 
 @attrs.frozen
-class MemoryChannelStats:
+class MemoryChannelStatistics:
     current_buffer_used: int
     max_buffer_size: int | float
     open_send_channels: int
@@ -132,8 +132,8 @@ class MemoryChannelState(Generic[T]):
     # {task: None}
     receive_tasks: OrderedDict[Task, None] = attrs.Factory(OrderedDict)
 
-    def statistics(self) -> MemoryChannelStats:
-        return MemoryChannelStats(
+    def statistics(self) -> MemoryChannelStatistics:
+        return MemoryChannelStatistics(
             current_buffer_used=len(self.data),
             max_buffer_size=self.max_buffer_size,
             open_send_channels=self.open_send_channels,
@@ -159,7 +159,9 @@ def __attrs_post_init__(self) -> None:
     def __repr__(self) -> str:
         return f"<send channel at {id(self):#x}, using buffer at {id(self._state):#x}>"
 
-    def statistics(self) -> MemoryChannelStats:
+    def statistics(self) -> MemoryChannelStatistics:
+        """Returns a `MemoryChannelStatistics` for the memory channel this is
+        associated with."""
         # XX should we also report statistics specific to this object?
         return self._state.statistics()
 
@@ -282,6 +284,9 @@ def close(self) -> None:
 
     @enable_ki_protection
     async def aclose(self) -> None:
+        """Close this send channel object asynchronously.
+
+        See `MemorySendChannel.close`."""
         self.close()
         await trio.lowlevel.checkpoint()
 
@@ -296,7 +301,9 @@ class MemoryReceiveChannel(ReceiveChannel[ReceiveType], metaclass=NoPublicConstr
     def __attrs_post_init__(self) -> None:
         self._state.open_receive_channels += 1
 
-    def statistics(self) -> MemoryChannelStats:
+    def statistics(self) -> MemoryChannelStatistics:
+        """Returns a `MemoryChannelStatistics` for the memory channel this is
+        associated with."""
         return self._state.statistics()
 
     def __repr__(self) -> str:
@@ -430,5 +437,8 @@ def close(self) -> None:
 
     @enable_ki_protection
     async def aclose(self) -> None:
+        """Close this receive channel object asynchronously.
+
+        See `MemoryReceiveChannel.close`."""
         self.close()
         await trio.lowlevel.checkpoint()

src/trio/_tests/_check_type_completeness.json

@@ -20,13 +20,10 @@
     "all": [
         "No docstring found for class \"trio.MemoryReceiveChannel\"",
         "No docstring found for class \"trio._channel.MemoryReceiveChannel\"",
-        "No docstring found for function \"trio._channel.MemoryReceiveChannel.statistics\"",
-        "No docstring found for class \"trio._channel.MemoryChannelStats\"",
-        "No docstring found for function \"trio._channel.MemoryReceiveChannel.aclose\"",
+        "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 function \"trio._channel.MemorySendChannel.statistics\"",
-        "No docstring found for function \"trio._channel.MemorySendChannel.aclose\"",
         "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\"",