Document that time-to-days and days-to-time use different epochs

* doc/lispref/os.texi (Time Calculations):
* lisp/calendar/time-date.el (days-to-time, time-to-days): Doc fixes.
(Bug#66502)

1 files changed, 8 insertions, 0 deletions

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 7c8b35236cd..ea27af8edb2 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2104,6 +2104,14 @@ This function returns the number of days between the beginning of year
 The operating system limits the range of time and zone values.
 @end defun
 
+@defun days-to-time days
+This is not quite the inverse of the @code{time-to-days} function, as
+it uses the Emacs epoch (instead of the year 1) for historical
+reasons.  To get the inverse, subtract @code{(time-to-days 0)} from
+@var{days}, in which case @code{days-to-time} may return @code{nil} if
+@var{days} is negative.
+@end defun
+
 @defun time-to-day-in-year time-value
 This returns the day number within the year corresponding to @var{time-value},
 assuming the default time zone.