[Emacs-diffs] emacs-26 b8c7017: Improve documentation of 'date-to-time' and 'parse-time-string'

[Eli Zaretskii]

branch: emacs-26
commit b8c70172f354ad57bb6c547d59f585d751f632ed
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Improve documentation of 'date-to-time' and 'parse-time-string'
    
    * doc/lispref/os.texi (Time Parsing): Document
    'parse-time-string', and refer to it for the description of
    the argument of 'date-to-time'.
    
    * lisp/calendar/time-date.el (date-to-time): Refer in the doc
    string to 'parse-time-string' for more information about the
    format of the DATE argument.  (Bug#34303)
---
 doc/lispref/os.texi        | 23 ++++++++++++++++++++++-
 lisp/calendar/time-date.el |  1 +
 2 files changed, 23 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 65c5706..2f3e91c 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1467,7 +1467,28 @@ integers (@pxref{Time of Day}).
 
 @defun date-to-time string
 This function parses the time-string @var{string} and returns the
-corresponding time value.
+corresponding time value.  The argument @var{string} should represent
+a date-time, and should be in one of the forms recognized by
address@hidden (see below).  This function assumes the GMT
+timezone if @var{string} lacks an explicit timezone information.
address@hidden defun
+
address@hidden parse-time-string string
+This function parses the time-string @var{string} into a list of the
+following form:
+
address@hidden
+(@var{sec} @var{min} @var{hour} @var{day} @var{mon} @var{year} @var{dow} 
@var{dst} @var{tz})
address@hidden example
+
address@hidden
+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
+element that cannot be determined from the input will be set to
address@hidden  The argument @var{string} should resemble an RFC 2822 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
 
 @defun format-time-string format-string &optional time zone
diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el
index 6988e65..afd5c09 100644
--- a/lisp/calendar/time-date.el
+++ b/lisp/calendar/time-date.el
@@ -148,6 +148,7 @@ it is assumed that PICO was omitted and should be treated 
as zero."
 ;; values.  timezone-make-date-arpa-standard should help.
 (defun date-to-time (date)
   "Parse a string DATE that represents a date-time and return a time value.
+DATE should be in one of the forms recognized by `parse-time-string'.
 If DATE lacks timezone information, GMT is assumed."
   (condition-case err
       (apply 'encode-time (parse-time-string date))