Document representation of dates in calendar.el

* lisp/calendar/calendar.el: Add a comment in file header
explaining how dates are represented.

diff --git a/lisp/calendar/calendar.el b/lisp/calendar/calendar.el
index 345687d177503eb76c4a8778c4d04ffa778f592b..f5066c61ae28c8b7b9bc3c83be0614188670973a 100644 (file)
--- a/lisp/calendar/calendar.el
+++ b/lisp/calendar/calendar.el
@@ -90,6 +90,16 @@
 ;; <https://doi.org/10.1002/spe.4380230404>
 ;; <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.42.6421&rep=rep1&type=pdf>
 
+;; A note on how dates are represented:
+
+;; The standard format for a (Gregorian) calendar date in this file is a
+;; list of integers (MONTH DAY YEAR) -- see the functions
+;; `calendar-extract-year', `calendar-extract-month', and
+;; `calendar-extract-day'.  Internally it also uses an "absolute" format
+;; which is an integer number of days since December 31, 1BC (see
+;; e.g. `calendar-absolute-from-gregorian'), and converts between
+;; different calendar scales by converting to and from the absolute
+;; format (see e.g. `calendar-iso-from-absolute' in cal-iso.el).
 
 ;; A note on free variables: