bpo-28157: Improvements for the time module documentation (GH-928)

* Separated functions and constants descriptions in sections.
* Added a note about the limitations of timezone constants.
* Removed redundant lists from the module docstring.

2 files changed, 116 insertions, 109 deletions

diff --git a/Doc/library/time.rst b/Doc/library/time.rst
index 179762e..25a4ab5 100644
--- a/Doc/library/time.rst
+++ b/Doc/library/time.rst
@@ -118,14 +118,10 @@ An explanation of some terminology and conventions is in order.
   +-------------------------+-------------------------+-------------------------+
 
 
-The module defines the following functions and data items:
-
-.. data:: altzone
-
-   The offset of the local DST timezone, in seconds west of UTC, if one is defined.
-   This is negative if the local DST timezone is east of UTC (as in Western Europe,
-   including the UK).  Only use this if ``daylight`` is nonzero.
+.. _time-functions:
 
+Functions
+---------
 
 .. function:: asctime([t])
 
@@ -181,7 +177,8 @@ The module defines the following functions and data items:
 
 .. function:: clock_getres(clk_id)
 
-   Return the resolution (precision) of the specified clock *clk_id*.
+   Return the resolution (precision) of the specified clock *clk_id*.  Refer to
+   :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
 
    Availability: Unix.
 
@@ -190,7 +187,8 @@ The module defines the following functions and data items:
 
 .. function:: clock_gettime(clk_id)
 
-   Return the time of the specified clock *clk_id*.
+   Return the time of the specified clock *clk_id*.  Refer to
+   :ref:`time-clock-id-constants` for a list of accepted values for *clk_id*.
 
    Availability: Unix.
 
@@ -199,66 +197,8 @@ The module defines the following functions and data items:
 
 .. function:: clock_settime(clk_id, time)
 
-   Set the time of the specified clock *clk_id*.
-
-   Availability: Unix.
-
-   .. versionadded:: 3.3
-
-
-.. data:: CLOCK_HIGHRES
-
-   The Solaris OS has a CLOCK_HIGHRES timer that attempts to use an optimal
-   hardware source, and may give close to nanosecond resolution.  CLOCK_HIGHRES
-   is the nonadjustable, high-resolution clock.
-
-   Availability: Solaris.
-
-   .. versionadded:: 3.3
-
-
-.. data:: CLOCK_MONOTONIC
-
-   Clock that cannot be set and represents monotonic time since some unspecified
-   starting point.
-
-   Availability: Unix.
-
-   .. versionadded:: 3.3
-
-
-.. data:: CLOCK_MONOTONIC_RAW
-
-   Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw
-   hardware-based time that is not subject to NTP adjustments.
-
-   Availability: Linux 2.6.28 or later.
-
-   .. versionadded:: 3.3
-
-
-.. data:: CLOCK_PROCESS_CPUTIME_ID
-
-   High-resolution per-process timer from the CPU.
-
-   Availability: Unix.
-
-   .. versionadded:: 3.3
-
-
-.. data:: CLOCK_REALTIME
-
-   System-wide real-time clock.  Setting this clock requires appropriate
-   privileges.
-
-   Availability: Unix.
-
-   .. versionadded:: 3.3
-
-
-.. data:: CLOCK_THREAD_CPUTIME_ID
-
-   Thread-specific CPU-time clock.
+   Set the time of the specified clock *clk_id*.  Currently,
+   :data:`CLOCK_REALTIME` is the only accepted value for *clk_id*.
 
    Availability: Unix.
 
@@ -273,11 +213,6 @@ The module defines the following functions and data items:
    ``asctime(localtime(secs))``. Locale information is not used by :func:`ctime`.
 
 
-.. data:: daylight
-
-   Nonzero if a DST timezone is defined.
-
-
 .. function:: get_clock_info(name)
 
    Get information on the specified clock as a namespace object.
@@ -295,7 +230,7 @@ The module defines the following functions and data items:
    - *adjustable*: ``True`` if the clock can be changed automatically (e.g. by
      a NTP daemon) or manually by the system administrator, ``False`` otherwise
    - *implementation*: The name of the underlying C function used to get
-     the clock value
+     the clock value.  Refer to :ref:`time-clock-id-constants` for possible values.
    - *monotonic*: ``True`` if the clock cannot go backward,
      ``False`` otherwise
    - *resolution*: The resolution of the clock in seconds (:class:`float`)
@@ -623,18 +558,6 @@ The module defines the following functions and data items:
    :class:`struct_time` object is returned, from which the components
    of the calendar date may be accessed as attributes.
 
-.. data:: timezone
-
-   The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
-   most of Western Europe, positive in the US, zero in the UK).
-
-
-.. data:: tzname
-
-   A tuple of two strings: the first is the name of the local non-DST timezone, the
-   second is the name of the local DST timezone.  If no DST timezone is defined,
-   the second string should not be used.
-
 
 .. function:: tzset()
 
@@ -724,6 +647,111 @@ The module defines the following functions and data items:
       ('EET', 'EEST')
 
 
+.. _time-clock-id-constants:
+
+Clock ID Constants
+------------------
+
+These constants are used as parameters for :func:`clock_getres` and
+:func:`clock_gettime`.
+
+.. data:: CLOCK_HIGHRES
+
+   The Solaris OS has a ``CLOCK_HIGHRES`` timer that attempts to use an optimal
+   hardware source, and may give close to nanosecond resolution.
+   ``CLOCK_HIGHRES`` is the nonadjustable, high-resolution clock.
+
+   Availability: Solaris.
+
+   .. versionadded:: 3.3
+
+
+.. data:: CLOCK_MONOTONIC
+
+   Clock that cannot be set and represents monotonic time since some unspecified
+   starting point.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: CLOCK_MONOTONIC_RAW
+
+   Similar to :data:`CLOCK_MONOTONIC`, but provides access to a raw
+   hardware-based time that is not subject to NTP adjustments.
+
+   Availability: Linux 2.6.28 or later.
+
+   .. versionadded:: 3.3
+
+
+.. data:: CLOCK_PROCESS_CPUTIME_ID
+
+   High-resolution per-process timer from the CPU.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. data:: CLOCK_THREAD_CPUTIME_ID
+
+   Thread-specific CPU-time clock.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+The following constant is the only parameter that can be sent to
+:func:`clock_settime`.
+
+.. data:: CLOCK_REALTIME
+
+   System-wide real-time clock.  Setting this clock requires appropriate
+   privileges.
+
+   Availability: Unix.
+
+   .. versionadded:: 3.3
+
+
+.. _time-timezone-constants:
+
+Timezone Constants
+-------------------
+
+.. data:: altzone
+
+   The offset of the local DST timezone, in seconds west of UTC, if one is defined.
+   This is negative if the local DST timezone is east of UTC (as in Western Europe,
+   including the UK).  Only use this if ``daylight`` is nonzero.  See note below.
+
+.. data:: daylight
+
+   Nonzero if a DST timezone is defined.  See note below.
+
+.. data:: timezone
+
+   The offset of the local (non-DST) timezone, in seconds west of UTC (negative in
+   most of Western Europe, positive in the US, zero in the UK).  See note below.
+
+.. data:: tzname
+
+   A tuple of two strings: the first is the name of the local non-DST timezone, the
+   second is the name of the local DST timezone.  If no DST timezone is defined,
+   the second string should not be used.  See note below.
+
+.. note::
+
+   For the above Timezone constants (:data:`altzone`, :data:`daylight`, :data:`timezone`,
+   and :data:`tzname`), the value is determined by the timezone rules in effect
+   at module load time or the last time :func:`tzset` is called and may be incorrect
+   for times in the past.  It is recommended to use the :attr:`tm_gmtoff` and
+   :attr:`tm_zone` results from :func:`localtime` to obtain timezone information.
+
+
 .. seealso::
 
    Module :mod:`datetime`
diff --git a/Modules/timemodule.c b/Modules/timemodule.c
index 31050fb..2c0a8d6 100644
--- a/Modules/timemodule.c
+++ b/Modules/timemodule.c
@@ -1342,28 +1342,7 @@ The tuple items are:\n\
   DST (Daylight Savings Time) flag (-1, 0 or 1)\n\
 If the DST flag is 0, the time is given in the regular time zone;\n\
 if it is 1, the time is given in the DST time zone;\n\
-if it is -1, mktime() should guess based on the date and time.\n\
-\n\
-Variables:\n\
-\n\
-timezone -- difference in seconds between UTC and local standard time\n\
-altzone -- difference in  seconds between UTC and local DST time\n\
-daylight -- whether local time should reflect DST\n\
-tzname -- tuple of (standard time zone name, DST time zone name)\n\
-\n\
-Functions:\n\
-\n\
-time() -- return current time in seconds since the Epoch as a float\n\
-clock() -- return CPU time since process start as a float\n\
-sleep() -- delay for a number of seconds given as a float\n\
-gmtime() -- convert seconds since Epoch to UTC tuple\n\
-localtime() -- convert seconds since Epoch to local time tuple\n\
-asctime() -- convert time tuple to string\n\
-ctime() -- convert time in seconds to string\n\
-mktime() -- convert local time tuple to seconds since Epoch\n\
-strftime() -- convert time tuple to string according to format specification\n\
-strptime() -- parse string to time tuple according to format specification\n\
-tzset() -- change the local timezone");
+if it is -1, mktime() should guess based on the date and time.\n");