[3.15] Fix various issues in the 'Timer File Descriptors' documentation (GH-156027)

(cherry picked from commit 13ab4c2)

Co-authored-by: Omar Sandoval <osandov@osandov.com>
Co-authored-by: Stan Ulbrych <stan@python.org>

Author: osandov

Doc/library/os.rst

@@ -4553,16 +4553,17 @@ Naturally, they are all only available on Linux.
    - :const:`time.CLOCK_BOOTTIME` (Since Linux 3.15 for timerfd_create)
 
    If *clockid* is :const:`time.CLOCK_REALTIME`, a settable system-wide
-   real-time clock is used. If system clock is changed, timer setting need
-   to be updated. To cancel timer when system clock is changed, see
+   real-time clock is used. If the system clock is changed, the timer setting
+   needs to be updated. To cancel the timer when the system clock is changed, see
    :const:`TFD_TIMER_CANCEL_ON_SET`.
 
    If *clockid* is :const:`time.CLOCK_MONOTONIC`, a non-settable monotonically
    increasing clock is used. Even if the system clock is changed, the timer
    setting will not be affected.
 
-   If *clockid* is :const:`time.CLOCK_BOOTTIME`, same as :const:`time.CLOCK_MONOTONIC`
-   except it includes any time that the system is suspended.
+   If *clockid* is :const:`time.CLOCK_BOOTTIME`, it is the same as
+   :const:`time.CLOCK_MONOTONIC` except it includes any time that the system
+   is suspended.
 
    The file descriptor's behaviour can be modified by specifying a *flags* value.
    Any of the following variables may be used, combined using bitwise OR
@@ -4573,8 +4574,8 @@ Naturally, they are all only available on Linux.
 
    If :const:`TFD_NONBLOCK` is not set as a flag, :func:`read` blocks until
    the timer expires. If it is set as a flag, :func:`read` doesn't block, but
-   If there hasn't been an expiration since the last call to read,
-   :func:`read` raises :class:`OSError` with ``errno`` is set to
+   if there hasn't been an expiration since the last call to read,
+   :func:`read` raises :class:`OSError` with ``errno`` set to
    :const:`errno.EAGAIN`.
 
    :const:`TFD_CLOEXEC` is always set by Python automatically.
@@ -4589,7 +4590,7 @@ Naturally, they are all only available on Linux.
    .. versionadded:: 3.13
 
 
-.. function:: timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0)
+.. function:: timerfd_settime(fd, /, *, flags=0, initial=0.0, interval=0.0)
 
    Alter a timer file descriptor's internal timer.
    This function operates the same interval timer as :func:`timerfd_settime_ns`.
@@ -4604,12 +4605,11 @@ Naturally, they are all only available on Linux.
    - :const:`TFD_TIMER_CANCEL_ON_SET`
 
    The timer is disabled by setting *initial* to zero (``0``).
-   If *initial* is equal to or greater than zero, the timer is enabled.
+   If *initial* is greater than zero, the timer is enabled.
    If *initial* is less than zero, it raises an :class:`OSError` exception
-   with ``errno`` set to :const:`errno.EINVAL`
+   with ``errno`` set to :const:`errno.EINVAL`.
 
    By default the timer will fire when *initial* seconds have elapsed.
-   (If *initial* is zero, timer will fire immediately.)
 
    However, if the :const:`TFD_TIMER_ABSTIME` flag is set,
    the timer will fire when the timer's clock
@@ -4620,13 +4620,13 @@ Naturally, they are all only available on Linux.
    If *interval* is greater than zero, the timer fires every time *interval*
    seconds have elapsed since the previous expiration.
    If *interval* is less than zero, it raises :class:`OSError` with ``errno``
-   set to :const:`errno.EINVAL`
+   set to :const:`errno.EINVAL`.
 
    If the :const:`TFD_TIMER_CANCEL_ON_SET` flag is set along with
    :const:`TFD_TIMER_ABSTIME` and the clock for this timer is
    :const:`time.CLOCK_REALTIME`, the timer is marked as cancelable if the
    real-time clock is changed discontinuously. Reading the descriptor is
-   aborted with the error ECANCELED.
+   aborted with the error :const:`errno.ECANCELED`.
 
    Linux manages system clock as UTC. A daylight-savings time transition is
    done by changing time offset only and doesn't cause discontinuous system

Modules/clinic/posixmodule.c.h

@@ -11471,17 +11471,17 @@ os.timerfd_settime_ns
     flags: int = 0
         0 or a bit mask of TFD_TIMER_ABSTIME or TFD_TIMER_CANCEL_ON_SET.
     initial: long_long = 0
-        initial expiration timing in seconds.
+        initial expiration timing in nanoseconds.
     interval: long_long = 0
-        interval for the timer in seconds.
+        interval for the timer in nanoseconds.
 
 Alter a timer file descriptor's internal timer in nanoseconds.
 [clinic start generated code]*/
 
 static PyObject *
 os_timerfd_settime_ns_impl(PyObject *module, int fd, int flags,
                            long long initial, long long interval)
-/*[clinic end generated code: output=6273ec7d7b4cc0b3 input=261e105d6e42f5bc]*/
+/*[clinic end generated code: output=6273ec7d7b4cc0b3 input=94bdcea7292157eb]*/
 {
     struct itimerspec new_value;
     struct itimerspec old_value;
@@ -11511,12 +11511,12 @@ os.timerfd_gettime
         A timer file descriptor.
     /
 
-Return a tuple of a timer file descriptor's (interval, next expiration) in float seconds.
+Return a tuple of a timer file descriptor's (next expiration, interval) in float seconds.
 [clinic start generated code]*/
 
 static PyObject *
 os_timerfd_gettime_impl(PyObject *module, int fd)
-/*[clinic end generated code: output=ec5a94a66cfe6ab4 input=05f7d568a4820dc6]*/
+/*[clinic end generated code: output=ec5a94a66cfe6ab4 input=7b0a7cc61ea9e31a]*/
 {
     struct itimerspec curr_value;
     int result;
@@ -11538,12 +11538,12 @@ os.timerfd_gettime_ns
         A timer file descriptor.
     /
 
-Return a tuple of a timer file descriptor's (interval, next expiration) in nanoseconds.
+Return a tuple of a timer file descriptor's (next expiration, interval) in nanoseconds.
 [clinic start generated code]*/
 
 static PyObject *
 os_timerfd_gettime_ns_impl(PyObject *module, int fd)
-/*[clinic end generated code: output=580633a4465f39fe input=d0de95b9782179c5]*/
+/*[clinic end generated code: output=580633a4465f39fe input=89702268455fa93b]*/
 {
     struct itimerspec curr_value;
     int result;