nstrftime: Document the nstrftime function

[Bruno Haible]

Simon Josefsson asked, in
<https://lists.gnu.org/archive/html/bug-gnulib/2024-02/msg00030.html>,
for a *documented* replacement of 'ctime' or 'asctime'.

So, let's start by documenting nstrftime properly. So far, its documentation
  - lacks statements about the roles and semantics of the first 4 arguments,
  - refers to 'strftime', leaving it unclear whether it means ISO C strftime,
    POSIX strftime, or GNU strftime,
  - lacks a statement about whether providing a too small buffer is considered
    an error or not,
  - does not state how to find the time zone argument to pass.


2024-02-07  Bruno Haible  <bruno@clisp.org>

        nstrftime: Document the nstrftime function.
        * lib/strftime.h (nstrftime): Add more comments.

diff --git a/lib/strftime.h b/lib/strftime.h
index d6efdb848a..8fff11bec1 100644
--- a/lib/strftime.h
+++ b/lib/strftime.h
@@ -21,17 +21,62 @@
 extern "C" {
 #endif
 
-/* Just like strftime, but with two more arguments:
-   POSIX requires that strftime use the local timezone information.
-   Use the timezone __TZ instead.  Use __NS as the number of
-   nanoseconds in the %N directive.
-
-   On error, set errno and return 0.  Otherwise, return the number of
-   bytes generated (not counting the trailing NUL), preserving errno
-   if the number is 0.  This errno behavior is in draft POSIX 202x
-   plus some requested changes to POSIX.  */
-size_t nstrftime (char *restrict, size_t, char const *, struct tm const *,
-                  timezone_t __tz, int __ns);
+/* Formats the broken-down time *__TP, with additional __NS nanoseconds,
+   into the buffer __S of size __MAXSIZE, according to the rules of the
+   LC_TIME category of the current locale.
+
+   Uses the time zone __TZ.
+   If *__TP represents local time, _TZ should be set to
+     tzalloc (getenv ("TZ")).
+   If *__TP represents universal time (a.k.a. GMT), __TZ should be set to
+     (timezone_t) 0.
+
+   The format string __FORMAT, including GNU extensions, is described in
+   the GNU libc's strftime() documentation:
+   
<https://www.gnu.org/software/libc/manual/html_node/Formatting-Calendar-Time.html>
+   Additionally, the following conversion is supported:
+     %N   The number of nanoseconds, passed as __NS argument.
+   Here's a summary of the available conversions (= format directives):
+     literal characters      %n %t %%
+     date:
+       century               %C
+       year                  %Y %y
+       week-based year       %G %g
+       month (in year)       %m %B %b %h
+       week in year          %U %W %V
+       day in year           %j
+       day (in month)        %d %e
+       day in week           %u %w %A %a
+       year, month, day      %x %F %D
+     time:
+       half-day              %p %P
+       hour                  %H %k %I %l
+       minute (in hour)      %M
+       hour, minute          %R
+       second (in minute)    %S
+       hour, minute, second  %r %T %X
+       second (since epoch)  %s
+     date and time:          %c
+     time zone:              %z %Z
+     nanosecond              %N
+
+   Stores the result, as a string with a trailing NUL character, at the
+   beginning of the array __S[0..__MAXSIZE-1], if it fits, and returns
+   the length of that string, not counting the trailing NUL.  In this case,
+   errno is preserved if the return value is 0.
+   If it does not fit, this function sets errno to ERANGE and returns 0.
+   Upon other errors, this function sets errno and returns 0 as well.
+
+   Note: The errno behavior is in draft POSIX 202x plus some requested
+   changes to POSIX.
+
+   This function is like strftime, but with two more arguments:
+     * __TZ instead of the local timezone information,
+     * __NS as the number of nanoseconds in the %N directive.
+ */
+size_t nstrftime (char *restrict __s, size_t __maxsize,
+                  char const *__format,
+                  struct tm const *__tp, timezone_t __tz, int __ns);
 
 #ifdef __cplusplus
 }