Explicitly document the methods

srittau · srittau · commit 4d50c2eda68c · 2024-12-05T20:44:23.000+01:00
Small improvements to the docstrings and signature
diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
@@ -2821,8 +2821,21 @@ decorated with :func:`@runtime_checkable <runtime_checkable>`.
 
 .. class:: Reader[T]
 
-   Protocol for reading from a file or other input stream. Implementations
-   must support the ``read``, ``readline``, and ``__iter__`` methods.
+   Protocol for reading from a file or other input stream.
+
+   .. method:: read(size=...)
+
+        Read data from the input stream and return it. If ``size`` is
+        specified, at most ``size`` items (bytes/characters) will be read.
+
+   .. method:: readline(size=...)
+
+        Read a line of data from the input stream and return it. If ``size`` is
+        specified, at most ``size`` items (bytes/characters) will be read.
+
+   .. method:: __iter__()
+
+        Read a line of data from the input stream and return it.
 
    For example::
 
@@ -2833,8 +2846,12 @@ decorated with :func:`@runtime_checkable <runtime_checkable>`.
 
 .. class:: Writer[T]
 
-   Protocol for writing to a file or other output stream. Implementations
-   must support the ``write`` method.
+   Protocol for writing to a file or other output stream.
+
+   .. method:: write(data)
+
+      Write data to the output stream and return number of items
+      (bytes/characters) written.
 
    For example::
 
diff --git a/Lib/typing.py b/Lib/typing.py
@@ -2937,13 +2937,14 @@ class Reader[T](Iterable[T], Protocol):
     __slots__ = ()
 
     def read(self, size: int = ..., /) -> T:
-        """Read data from the I/O stream and return it.
+        """Read data from the input stream and return it.
 
         If "size" is specified, at most "size" items (bytes/characters) will be
         read.
         """
+
     def readline(self, size: int = ..., /) -> T:
-        """Read a line of data from the I/O stream and return it.
+        """Read a line of data from the input stream and return it.
 
         If "size" is specified, at most "size" items (bytes/characters) will be
         read.
@@ -2959,8 +2960,8 @@ class Writer[T](Protocol):
 
     __slots__ = ()
 
-    def write(self, o: T, /) -> int:
-        """Write data to the I/O stream and return number of items written."""
+    def write(self, data: T, /) -> int:
+        """Write data to the output stream and return number of items written."""
 
 
 def _make_nmtuple(name, fields, annotate_func, module, defaults = ()):
