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

(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>

3 files changed, 23 insertions, 14 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/clinic/iobase.c.h b/Modules/_io/clinic/iobase.c.h
index 773e001..e29a4f1 100644
--- a/Modules/_io/clinic/iobase.c.h
+++ b/Modules/_io/clinic/iobase.c.h
@@ -14,6 +14,11 @@ PyDoc_STRVAR(_io__IOBase_seek__doc__,
 "\n"
 "Change the stream position to the given byte offset.\n"
 "\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"
@@ -436,4 +441,4 @@ _io__RawIOBase_readall(PyObject *self, PyObject *Py_UNUSED(ignored))
 {
     return _io__RawIOBase_readall_impl(self);
 }
-/*[clinic end generated code: output=301b22f8f75ce3dc input=a9049054013a1b77]*/
+/*[clinic end generated code: output=7c2df7a330be8b5b input=a9049054013a1b77]*/
diff --git a/Modules/_io/iobase.c b/Modules/_io/iobase.c
index bcb498d..bc2c9af 100644
--- a/Modules/_io/iobase.c
+++ b/Modules/_io/iobase.c
@@ -83,7 +83,9 @@ iobase_unsupported(_PyIO_State *state, const char *message)
 _io._IOBase.seek
     cls: defining_class
     offset: int(unused=True)
+      The stream position, relative to 'whence'.
     whence: int(unused=True, c_default='0') = os.SEEK_SET
+      The relative position to seek from.
     /
 
 Change the stream position to the given byte offset.
@@ -101,7 +103,7 @@ Return the new absolute position.
 static PyObject *
 _io__IOBase_seek_impl(PyObject *self, PyTypeObject *cls,
                       int Py_UNUSED(offset), int Py_UNUSED(whence))
-/*[clinic end generated code: output=8bd74ea6538ded53 input=8d4e6adcd08292f2]*/
+/*[clinic end generated code: output=8bd74ea6538ded53 input=74211232b363363e]*/
 {
     _PyIO_State *state = get_io_state_by_cls(cls);
     return iobase_unsupported(state, "seek");