[3.11] gh-107801: Improve the accuracy of io.IOBase.seek docs (#108268) (#108656)

(cherry picked from commit 8178a88bd81edae87d6974483e4de9b32e808797)

- Add param docstrings
- Link to os.SEEK_* constants
- Mention the return value in the initial paragraph

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

2 files changed, 28 insertions, 19 deletions

diff --git a/Doc/library/io.rst b/Doc/library/io.rst
index 25f4d0d..0108887 100644
--- a/Doc/library/io.rst
+++ b/Doc/library/io.rst
@@ -403,20 +403,19 @@ I/O Base Classes
       Note that it's already possible to iterate on file objects using ``for
       line in file: ...`` without calling :meth:`!file.readlines`.
 
-   .. method:: seek(offset, whence=SEEK_SET, /)
+   .. method:: seek(offset, whence=os.SEEK_SET, /)
 
-      Change the stream position to the given byte *offset*.  *offset* is
-      interpreted relative to the position indicated by *whence*.  The default
-      value for *whence* is :data:`!SEEK_SET`.  Values for *whence* are:
+      Change the stream position to the given byte *offset*,
+      interpreted relative to the position indicated by *whence*,
+      and return the new absolute position.
+      Values for *whence* are:
 
-      * :data:`!SEEK_SET` or ``0`` -- start of the stream (the default);
+      * :data:`os.SEEK_SET` or ``0`` -- start of the stream (the default);
         *offset* should be zero or positive
-      * :data:`!SEEK_CUR` or ``1`` -- current stream position; *offset* may
-        be negative
-      * :data:`!SEEK_END` or ``2`` -- end of the stream; *offset* is usually
-        negative
-
-      Return the new absolute position.
+      * :data:`os.SEEK_CUR` or ``1`` -- current stream position;
+        *offset* may be negative
+      * :data:`os.SEEK_END` or ``2`` -- end of the stream;
+        *offset* is usually negative
 
       .. versionadded:: 3.1
          The :data:`!SEEK_*` constants.
@@ -1061,6 +1060,10 @@ Text I/O
       Any other argument combinations are invalid,
       and may raise exceptions.
 
+      .. seealso::
+
+         :data:`os.SEEK_SET`, :data:`os.SEEK_CUR`, and :data:`os.SEEK_END`.
+
    .. method:: tell()
 
       Return the stream position as an opaque number.
@@ -1068,7 +1071,6 @@ Text I/O
       to restore a previous stream position.
 
 
-
 .. class:: StringIO(initial_value='', newline='\n')
 
    A text stream using an in-memory text buffer.  It inherits
diff --git a/Modules/_io/iobase.c b/Modules/_io/iobase.c
index 6ae43a8..8424fab 100644
--- a/Modules/_io/iobase.c
+++ b/Modules/_io/iobase.c
@@ -82,15 +82,22 @@ iobase_unsupported(const char *message)
 /* Positioning */
 
 PyDoc_STRVAR(iobase_seek_doc,
-    "Change stream position.\n"
+    "seek($self, offset, whence=os.SEEK_SET, /)\n"
+    "--\n"
     "\n"
-    "Change the stream position to the given byte offset. The offset is\n"
-    "interpreted relative to the position indicated by whence.  Values\n"
-    "for whence are:\n"
+    "Change the stream position to the given byte offset.\n"
     "\n"
-    "* 0 -- start of stream (the default); offset should be zero or positive\n"
-    "* 1 -- current stream position; offset may be negative\n"
-    "* 2 -- end of stream; offset is usually negative\n"
+    "  offset\n"
+    "    The stream position, relative to \'whence\'.\n"
+    "  whence\n"
+    "    The relative position to seek from.\n"
+    "\n"
+    "The offset is interpreted relative to the position indicated by whence.\n"
+    "Values for whence are:\n"
+    "\n"
+    "* os.SEEK_SET or 0 -- start of stream (the default); offset should be zero or positive\n"
+    "* os.SEEK_CUR or 1 -- current stream position; offset may be negative\n"
+    "* os.SEEK_END or 2 -- end of stream; offset is usually negative\n"
     "\n"
     "Return the new absolute position.");