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

2 files changed, 9 insertions, 2 deletions

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