[3.12] gh-107801: Improve the accuracy of os.lseek docs (#107935) (#108136)

- name the last parameter *whence*, like it is for seek() methods on
  file objects
- add param docstrings
- structure the valid *whence* params

(cherry picked from commit dd4442c8f597af1ec3eaf20f7ad89c4ac7e2dbc9)

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

1 files changed, 9 insertions, 4 deletions

diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
index b9f45c0..44cc31b 100644
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -10421,19 +10421,24 @@ os_lockf_impl(PyObject *module, int fd, int command, Py_off_t length)
 os.lseek -> Py_off_t
 
     fd: int
+        An open file descriptor, as returned by os.open().
     position: Py_off_t
-    how: int
+        Position, interpreted relative to 'whence'.
+    whence as how: int
+        The relative position to seek from. Valid values are:
+        - SEEK_SET: seek from the start of the file.
+        - SEEK_CUR: seek from the current file position.
+        - SEEK_END: seek from the end of the file.
     /
 
 Set the position of a file descriptor.  Return the new position.
 
-Return the new cursor position in number of bytes
-relative to the beginning of the file.
+The return value is the number of bytes relative to the beginning of the file.
 [clinic start generated code]*/
 
 static Py_off_t
 os_lseek_impl(PyObject *module, int fd, Py_off_t position, int how)
-/*[clinic end generated code: output=971e1efb6b30bd2f input=902654ad3f96a6d3]*/
+/*[clinic end generated code: output=971e1efb6b30bd2f input=f096e754c5367504]*/
 {
     Py_off_t result;