[m-rev.] for review: improve the documentation of the calendar module

[Zoltan Somogyi]

On Tue, 17 Mar 2026 16:22:17 +1100, Julien Fischer <jfischer at opturion.com> wrote:
> > > > +    % The year must have at least four digits; years with more than four digits
> > > > +    % are accepted. The microseconds component (.mmmmmm) is optional. If
> > > > +    % present, it may have between one and six digits.
> > > > +    %
> > > > +    % Fail if the string does not conform to the above format, or if any
> > > > +    % date or time component is outside its valid range.
> > >
> > > What is the justification for restricting to 4+ digit years?
> >
> > Good question. The short answer is I don't know.
> > I intend to investigate further and lift the restriction if I can't
> > find a reason.

I wasn't arguing for dropping the restriction; I was arguing for
documenting the reason for it.

> Requiring that years have at least four digits in date-time
> representations comes
> from ISO 8601-1.  Other time-related standards have picked it up. For
> example, both RFC 3339 and the XML Schema standard on which this
> module was based.

Using that info, I wrote (and just committed) this diff. For your review.

Zoltan.

--- a/library/calendar.m
+++ b/library/calendar.m
@@ -162,12 +162,21 @@
 %---------------------%
 
     % Convert a string of the form "[-]YYYY-MM-DD HH:MM:SS.mmmmmm" to a date.
-    % The year must have at least four digits; years with more than four digits
-    % are accepted. The microseconds component (.mmmmmm) is optional. If
-    % present, it may have between one and six digits.
     %
-    % Fail if the string does not conform to the above format, or if any
-    % date or time component is outside its valid range.
+    % The year must have at least four digits. This requirement comes from
+    % ISO standard 8601, and its main intention is to prevent repeats of
+    % the Y2K problem (see https://en.wikipedia.org/wiki/Year_2000_problem).
+    % It also prevents possible confusion between the year part of the date,
+    % and the month or the day parts.
+    %
+    % Since some simulation programs may want to handle dates in the far
+    % future, the predicate accepts years with more than four digits.
+    %
+    % The microseconds component (.mmmmmm) is optional. If present,
+    % it may have between one and six digits.
+    %
+    % This predicate fails if the string does not conform to the above format,
+    % or if any date or time component is outside its valid range.
     %
 :- pred date_from_string(string::in, date::out) is semidet.