From d742d4cde99941cabf86fb84ff5b38a61481ef95 Mon Sep 17 00:00:00 2001
From: Markus Triska <triska@metalevel.at>
Date: Tue, 24 Jan 2023 22:10:40 +0100
Subject: [PATCH] DOC: convert library(time) documentation to DocLog format

---
 src/lib/time.pl | 99 +++++++++++++++++++++++++++++--------------------
 1 file changed, 59 insertions(+), 40 deletions(-)

diff --git a/src/lib/time.pl b/src/lib/time.pl
index 20187c2d..47e02fc5 100644
--- a/src/lib/time.pl
+++ b/src/lib/time.pl
@@ -1,47 +1,11 @@
 /* - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-   Written 2020, 2021 by Markus Triska (triska@metalevel.at)
+   Written 2020-2023 by Markus Triska (triska@metalevel.at)
    Part of Scryer Prolog.
-
-   This library provides predicates for reasoning about time.
-
-   current_time(T) yields the current system time in an opaque form,
-   called a time stamp. Use format_time//2 to describe strings that
-   contain attributes of the time stamp.
-
-   The nonterminal format_time//2 describes a list of characters that
-   are formatted according to a format string. Usage:
-
-     phrase(format_time(FormatString, TimeStamp), Cs)
-
-   TimeStamp represents a moment in time in an opaque form, as for
-   example obtained by current_time/1.
-
-   FormatString is a list of characters that are interpreted literally,
-   except for the following specifiers (and possibly more in the future):
-
-     %Y    year of the time stamp. Example: 2020.
-     %m    month number (01-12), zero-padded to 2 digits
-     %d    day number (01-31), zero-padded to 2 digits
-     %H    hour number (00-24), zero-padded to 2 digits
-     %M    minute number (00-59), zero-padded to 2 digits
-     %S    second number (00-60), zero-padded to 2 digits
-     %b    abbreviated month name, always 3 letters
-     %a    abbreviated weekday name, always 3 letters
-     %A    full weekday name
-     %j    day of the year (001-366), zero-padded to 3 digits
-     %%    the literal %
-
-   Example:
-
-     ?- current_time(T), phrase(format_time("%d.%m.%Y (%H:%M:%S)", T), Cs).
-        T = [...], Cs = "11.06.2020 (00:24:32)".
-
-   sleep(S) sleeps for S seconds (a floating point number).
-
-   time(Goal) reports the execution time of Goal.
-
 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - */
 
+/** This library provides predicates for reasoning about time.
+*/
+
 :- module(time, [max_sleep_time/1, sleep/1, time/1, current_time/1, format_time//2]).
 
 :- use_module(library(format)).
@@ -51,10 +15,51 @@
 :- use_module(library(lists)).
 :- use_module(library(charsio), [read_from_chars/2]).
 
+
+%% current_time(-T)
+%
+%  Yields the current system time _T_ in an opaque form, called a
+%  _time stamp_. Use `format_time//2` to describe strings that contain
+%  attributes of the time stamp.
+
 current_time(T) :-
         '$current_time'(T0),
         read_from_chars(T0, T).
 
+%% format_time(FormatString, TimeStamp)//
+%
+%  The nonterminal format_time//2 describes a list of characters that
+%  are formatted according to a format string. Usage:
+%
+% ```
+%    phrase(format_time(FormatString, TimeStamp), Cs)
+% ```
+%
+%  TimeStamp represents a moment in time in an opaque form, as for
+%  example obtained by `current_time/1`.
+%
+%  FormatString is a list of characters that are interpreted literally,
+%  except for the following specifiers (and possibly more in the future):
+%
+%  |  %Y |  year of the time stamp. Example: 2020.                |
+%  |  %m |  month number (01-12), zero-padded to 2 digits         |
+%  |  %d |  day number (01-31), zero-padded to 2 digits           |
+%  |  %H |  hour number (00-24), zero-padded to 2 digits          |
+%  |  %M |  minute number (00-59), zero-padded to 2 digits        |
+%  |  %S |  second number (00-60), zero-padded to 2 digits        |
+%  |  %b |  abbreviated month name, always 3 letters              |
+%  |  %a |  abbreviated weekday name, always 3 letters            |
+%  |  %A |  full weekday name                                     |
+%  |  %j |  day of the year (001-366), zero-padded to 3 digits    |
+%  |  %% |  the literal %                                         |
+%
+%  Example:
+%
+% ```
+%    ?- current_time(T), phrase(format_time("%d.%m.%Y (%H:%M:%S)", T), Cs).
+%       T = [...], Cs = "11.06.2020 (00:24:32)".
+% ```
+
 format_time([], _) --> [].
 format_time(['%','%'|Fs], T) --> !, "%", format_time(Fs, T).
 format_time(['%',Spec|Fs], T) --> !,
@@ -65,8 +70,17 @@ format_time(['%',Spec|Fs], T) --> !,
         format_time(Fs, T).
 format_time([F|Fs], T) --> [F], format_time(Fs, T).
 
+%% max_sleep_time(T)
+%
+%  The maximum admissible time span for `sleep/1`.
+
 max_sleep_time(0xfffffffffffffbff).
 
+
+%% sleep(S)
+%
+%  Sleeps for S seconds (a floating point number or integer).
+
 sleep(T) :-
     builtins:must_be_number(T, sleep),
     (   T < 0 ->
@@ -91,6 +105,11 @@ time_next_id(N) :-
         ),
         asserta(time_id(N)).
 
+
+%% time(Goal)
+%
+%  Reports the execution time of Goal.
+
 time(Goal) :-
         '$cpu_now'(T0),
         time_next_id(ID),
-- 
2.54.0