Improve time function doc

* doc/misc/emacs-mime.texi (time-date): Don’t give
parse-iso8601-time-string in the example, as the function is
not autoloaded.
* lisp/gnus/nndiary.el (nndiary-compute-reminders):
No need to call encode-time or use floating point here.

7 files changed, 18 insertions, 18 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index b3444838d3b..7bb9833467d 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1559,7 +1559,7 @@ or more arguments.  The first six arguments @var{second},
 specify most of the components of a decoded time.  If there are more
 than six arguments the @emph{last} argument is used as @var{zone} and
 any other extra arguments are ignored, so that @code{(apply
-#\\='encode-time (decode-time ...))} works; otherwise @var{zone} defaults
+#'encode-time (decode-time ...))} works; otherwise @var{zone} defaults
 to the current time zone rule (@pxref{Time Zone Rules}).  The decoded
 time's @var{dst} component is treated as if it was @minus{}1, and
 @var{form} takes its default value.
@@ -1581,7 +1581,7 @@ You can perform simple date arithmetic by using out-of-range values for
 for example, day 0 means the day preceding the given month.
 
 The operating system puts limits on the range of possible time values;
-if you try to encode a time that is out of range, an error results.
+if the limits are exceeded while encoding the time, an error results.
 For instance, years before 1970 do not work on some systems;
 on others, years as early as 1901 do work.
 @end defun
diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index 6e95013c186..1f384f4f270 100644
--- a/doc/misc/emacs-mime.texi
+++ b/doc/misc/emacs-mime.texi
@@ -1541,10 +1541,6 @@ Here's a bunch of time/date/second/day examples:
              1000000)
 @result{} (905595714000000 . 1000000)
 
-(encode-time (parse-iso8601-time-string "1998-09-12T12:21:54+0200")
-             1000000)
-@result{} (905595714000000 . 1000000)
-
 (float-time '(905595714000000 . 1000000))
 @result{} 905595714.0
 
@@ -1627,7 +1623,7 @@ These are the functions available:
 Take a date and return a time.
 
 @item float-time
-Take a time and return seconds.  (This is a built-in function.)
+Take a time and return seconds.
 
 @item encode-time
 Take seconds (and other ways to represent time, notably decoded time
diff --git a/lisp/calendar/iso8601.el b/lisp/calendar/iso8601.el
index c69156cbeb6..30352c7e75f 100644
--- a/lisp/calendar/iso8601.el
+++ b/lisp/calendar/iso8601.el
@@ -138,7 +138,7 @@ well as variants like \"2008W32\" (week number) and
       date)))
 
 (defun iso8601-parse-date (string)
-  "Parse STRING (which should be on ISO 8601 format) and return a time value."
+  "Parse STRING (in ISO 8601 format) and return a decoded time value."
   (cond
    ;; Just a year: [-+]YYYY.
    ((iso8601--match iso8601--year-match string)
diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el
index 5b82b8ab0fa..c0565b3cfb7 100644
--- a/lisp/calendar/time-date.el
+++ b/lisp/calendar/time-date.el
@@ -374,8 +374,8 @@ January 1st being 1."
 
 (defun decoded-time-add (time delta)
   "Add DELTA to TIME, both of which are `decoded-time' structures.
-TIME should represent a time, while DELTA should only have
-non-nil integers for the values that should be altered.
+TIME should represent a time, while DELTA should have non-nil
+entries only for the values that should be altered.
 
 For instance, if you want to \"add two months\" to TIME, then
 leave all other fields but the month field in DELTA nil, and make
diff --git a/lisp/gnus/nndiary.el b/lisp/gnus/nndiary.el
index 2ad0634e6ad..8cda5aa7031 100644
--- a/lisp/gnus/nndiary.el
+++ b/lisp/gnus/nndiary.el
@@ -1278,27 +1278,27 @@ all.  This may very well take some time.")
        (cond ((eq (cdr reminder) 'minute)
               (time-subtract
                (apply #'encode-time 0 (nthcdr 1 date-elts))
-               (encode-time (* (car reminder) 60.0))))
+               (* (car reminder) 60)))
              ((eq (cdr reminder) 'hour)
               (time-subtract
                (apply #'encode-time 0 0 (nthcdr 2 date-elts))
-               (encode-time (* (car reminder) 3600.0))))
+               (* (car reminder) 3600)))
              ((eq (cdr reminder) 'day)
               (time-subtract
                (apply #'encode-time 0 0 0 (nthcdr 3 date-elts))
-               (encode-time (* (car reminder) 86400.0))))
+               (* (car reminder) 86400)))
              ((eq (cdr reminder) 'week)
               (time-subtract
                (apply #'encode-time 0 0 0 monday (nthcdr 4 date-elts))
-               (encode-time (* (car reminder) 604800.0))))
+               (* (car reminder) 604800)))
              ((eq (cdr reminder) 'month)
               (time-subtract
                (apply #'encode-time 0 0 0 1 (nthcdr 4 date-elts))
-               (encode-time (* (car reminder) 18748800.0))))
+               (* (car reminder) 18748800)))
              ((eq (cdr reminder) 'year)
               (time-subtract
                (apply #'encode-time 0 0 0 1 1 (nthcdr 5 date-elts))
-               (encode-time (* (car reminder) 400861056.0)))))
+               (* (car reminder) 400861056))))
        res))
     (sort res 'time-less-p)))
 
diff --git a/lisp/net/soap-client.el b/lisp/net/soap-client.el
index 5526d624f96..95f208baf98 100644
--- a/lisp/net/soap-client.el
+++ b/lisp/net/soap-client.el
@@ -636,6 +636,7 @@ disallows them."
       (error "Invalid or unsupported time: %s" date-time-string))
     ;; Return a value in a format similar to that returned by decode-time, and
     ;; suitable for (apply #'encode-time ...).
+    ;; FIXME: Nobody uses this idiosyncratic value.  Perhaps stop returning it?
     (list second minute hour day month year second-fraction datatype
           (if has-time-zone
               (* (rng-xsd-time-to-seconds
diff --git a/lisp/org/org-id.el b/lisp/org/org-id.el
index 44cc7b2f14d..8f9c132ad37 100644
--- a/lisp/org/org-id.el
+++ b/lisp/org/org-id.el
@@ -412,9 +412,12 @@ The input I may be a character, or a single-letter string."
     r))
 
 (defun org-id-time-to-b36 (&optional time)
-  "Encode TIME as a 10-digit string.
+  "Encode TIME as a 12-digit string.
 This string holds the time to micro-second accuracy, and can be decoded
 using `org-id-decode'."
+  ;; FIXME: If TIME represents N seconds after the epoch, then
+  ;; this encoding assumes 0 <= N < 110075314176 = (* (expt 36 4) 65536),
+  ;; i.e., that TIME is from 1970-01-01 00:00:00 to 5458-02-23 20:09:36 UTC.
   (setq time (encode-time time 'list))
   (concat (org-id-int-to-b36 (nth 0 time) 4)
           (org-id-int-to-b36 (nth 1 time) 4)
@@ -423,7 +426,7 @@ using `org-id-decode'."
 (defun org-id-decode (id)
   "Split ID into the prefix and the time value that was used to create it.
 The return value is (prefix . time) where PREFIX is nil or a string,
-and time is the usual three-integer representation of time."
+and TIME is a Lisp time value (HI LO USEC)."
   (let (prefix time parts)
     (setq parts (org-split-string id ":"))
     (if (= 2 (length parts))