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)

2 files changed, 23 insertions, 1 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 65c57064a3d..2f3e91ce68c 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
+@code{parse-time-string} (see below).  This function assumes the GMT
+timezone if @var{string} lacks an explicit timezone information.
+@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
+element that cannot be determined from the input will be set to
+@code{nil}.  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 6988e65dddc..afd5c091b40 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))