From 3254ff5b4fc12d24991f3c7d0fc90502b3381a5c Mon Sep 17 00:00:00 2001
From: "Erlend E. Aasland" <erlend@python.org>
Date: Mon, 14 Aug 2023 11:23:02 +0200
Subject: [PATCH] gh-107801: Improve the accuracy of os.lseek docs

- name the last parameter *whence*, like it is for seek() methods on
  file objects
- add param docstrings
- structure the valid *whence* values as a list
---
 Doc/library/os.rst    | 13 ++++++++-----
 Modules/posixmodule.c | 13 +++++++++----
 2 files changed, 17 insertions(+), 9 deletions(-)

diff --git a/Doc/library/os.rst b/Doc/library/os.rst
index 9735baa5bc0f3a..5582a3d7a6e14b 100644
--- a/Doc/library/os.rst
+++ b/Doc/library/os.rst
@@ -1163,13 +1163,16 @@ as internal buffering of data.
    .. versionadded:: 3.11
 
 
-.. function:: lseek(fd, pos, how, /)
+.. function:: lseek(fd, pos, whence, /)
 
    Set the current position of file descriptor *fd* to position *pos*, modified
-   by *how*: :const:`SEEK_SET` or ``0`` to set the position relative to the
-   beginning of the file; :const:`SEEK_CUR` or ``1`` to set it relative to the
-   current position; :const:`SEEK_END` or ``2`` to set it relative to the end of
-   the file. Return the new cursor position in bytes, starting from the beginning.
+   by *whence*, and return the new position in bytes, relative to
+   the start of the file.
+   Valid values for *whence* are:
+
+   * :const:`SEEK_SET` or ``0`` -- set *pos* relative to the beginning of the file
+   * :const:`SEEK_CUR` or ``1`` -- set *pos* relative to the current file position
+   * :const:`SEEK_END` or ``2`` -- set *pos* relative to the end of the file
 
 
 .. data:: SEEK_SET
diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
index a42e41c081e5b7..ae5c5f34e47c66 100644
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -10422,14 +10422,19 @@ 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.
+Set the position of a file descriptor, and 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