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

(cherry picked from commit 8178a88)

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

Co-authored-by: Adam Turner <[email protected]>

Author: erlend-aasland

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,14 +1060,17 @@ 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.
       The return value of :meth:`!tell` can be given as input to :meth:`seek`,
       to restore a previous stream position.
 
 
-
 .. class:: StringIO(initial_value='', newline='\n')
 
    A text stream using an in-memory text buffer.  It inherits

Modules/_io/clinic/iobase.c.h

@@ -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");