From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Fri, 17 Jun 2022 14:03:48 +0000 (+0200)
Subject: Improve time parsing documentation
X-Git-Tag: emacs-29.0.90~1447^2~1680
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=6db5c7f8c47590269d196a329eab727228b9be19;p=emacs.git

Improve time parsing documentation

* doc/lispref/os.texi (Time Parsing): Clarify which functions
take/return timestamps and which ones take decoded time structures.
* src/timefns.c (Fdecode_time): Clarify TIME argument (bug#46505).
---

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 11a0d02338f..bc5374f10f2 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1754,9 +1754,10 @@ at the 15th of the month when adding months.  Alternatively, you can use the
 @cindex time formatting
 @cindex formatting time values
 
-  These functions convert time values to text in a string, and vice versa.
-Time values include @code{nil}, finite numbers, and Lisp timestamps
-(@pxref{Time of Day}).
+  These functions convert time values to text in a string, and vice
+versa.  Time values are either represented as a Lisp timestamp
+(@pxref{Time of Day}) or a decoded time structure (@pxref{Time
+Conversion}).
 
 @defun date-to-time string
 This function parses the time-string @var{string} and returns the
@@ -1769,22 +1770,11 @@ The operating system limits the range of time and zone values.
 @end defun
 
 @defun parse-time-string string
-This function parses the time-string @var{string} into a list of the
-following form:
-
-@example
-(@var{sec} @var{min} @var{hour} @var{day} @var{mon} @var{year} @var{dow} @var{dst} @var{tz})
-@end example
-
-@noindent
-The format of this list is the same as what @code{decode-time} accepts
-(@pxref{Time Conversion}), and is described in more detail there.  Any
-@code{dst} element that cannot be determined from the input is set to
-@minus{}1, and any other unknown element is set to
-@code{nil}.  The argument @var{string} should resemble an RFC 822 (or later) or
-ISO 8601 string, like ``Fri, 25 Mar 2016 16:24:56 +0100'' or
-``1998-09-12T12:21:54-0200'', but this function will attempt to parse
-less well-formed time strings as well.
+This function parses the time-string @var{string} into a decoded time
+structure (@pxref{Time Conversion}).  The argument @var{string} should
+resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar
+2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this
+function will attempt to parse less well-formed time strings as well.
 @end defun
 
 @vindex ISO 8601 date/time strings
@@ -1801,11 +1791,11 @@ time structures, except the final one, which returns three of them
 @end defun
 
 @defun format-time-string format-string &optional time zone
-
-This function converts @var{time} (or the current time, if
-@var{time} is omitted or @code{nil}) to a string according to
-@var{format-string}.  The conversion uses the time zone rule @var{zone}, which
-defaults to the current time zone rule.  @xref{Time Zone Rules}.  The argument
+This function converts @var{time} (which should be a Lisp timestamp,
+and defaults to the current time if @var{time} is omitted or
+@code{nil}) to a string according to @var{format-string}.  The
+conversion uses the time zone rule @var{zone}, which defaults to the
+current time zone rule.  @xref{Time Zone Rules}.  The argument
 @var{format-string} may contain @samp{%}-sequences which say to
 substitute parts of the time.  Here is a table of what the
 @samp{%}-sequences mean:
diff --git a/src/timefns.c b/src/timefns.c
index 13a84f6b3ce..9df50eaecc3 100644
--- a/src/timefns.c
+++ b/src/timefns.c
@@ -1463,7 +1463,7 @@ usage: (format-time-string FORMAT-STRING &optional TIME ZONE)  */)
 }
 
 DEFUN ("decode-time", Fdecode_time, Sdecode_time, 0, 3, 0,
-       doc: /* Decode a time value as (SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).
+       doc: /* Decode a timestamp into (SEC MINUTE HOUR DAY MONTH YEAR DOW DST UTCOFF).
 The optional TIME is the time value to convert.  See
 `format-time-string' for the various forms of a time value.