Explicitly document the methods

Small improvements to the docstrings and signature
python · JelleZijlstra · Mar 6, 2025 · Dec 5, 2024 · Dec 5, 2024 · Dec 5, 2024
commit 4d50c2eda68c54044a45215d0cae873dd91d7458
@@ -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=...)
-   .. method:: read(size=...)
+   .. method:: read(size=..., /)
-   .. method:: read(size=...)
+   .. 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::


@@ -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 = ()):