xstrtod, xstrtold: Add documentation

[Bruno Haible]

Inspired by the discussion around xstrtol, I looked at xstrtod.

I plan to commit this documentation, when savannah allows. And to look
at the two FIXMEs regarding platform-dependent behaviour...


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

        xstrtod, xstrtold: Add documentation.
        * lib/xstrtod.h (xstrtod, xstrtold): Add comments.
        * lib/xstrtod.c (XSTRTOD): Add two FIXMEs.

diff --git a/lib/xstrtod.c b/lib/xstrtod.c
index 55b4bb4a8f..f99c943805 100644
--- a/lib/xstrtod.c
+++ b/lib/xstrtod.c
@@ -59,6 +59,8 @@ XSTRTOD (char const *str, char const **ptr, DOUBLE *result,
       /* Allow underflow (in which case CONVERT returns zero),
          but flag overflow as an error.  The user can decide
          to use the limits in RESULT upon ERANGE.  */
+      /* FIXME: Upon underflow, CONVERT may return non-zero.  */
+      /* FIXME: errno is unchanged if (math_errhandling & MATH_ERRNO) == 0.  */
       if (val != 0 && errno == ERANGE)
         ok = false;
     }
diff --git a/lib/xstrtod.h b/lib/xstrtod.h
index 9ae4be13da..a1d2ce06f7 100644
--- a/lib/xstrtod.h
+++ b/lib/xstrtod.h
@@ -26,8 +26,37 @@ extern "C" {
 #endif
 
 
+/* Converts the initial portion of the string starting at STR (if PTR != NULL)
+   or the entire string starting at STR (if PTR == NULL) to a number of type
+   'double'.
+   CONVERT should be a conversion function with the same calling conventions
+   as strtod, such as strtod or c_strtod.
+   If successful, it returns true, with *RESULT set to the result.
+   If it fails, it returns false, with *RESULT set to
+     - 0.0 upon conversion error,
+     - ±HUGE_VAL (i.e. ±Infinity) upon overflow,
+     - a value near zero upon underflow (only in implementations which consider
+       underflow to be an error),
+   and _maybe_ errno set as well.
+   In both cases, if PTR != NULL, *PTR is set to point to the character after
+   the parsed number.  */
 bool xstrtod (const char *str, const char **ptr, double *result,
               double (*convert) (char const *, char **));
+
+/* Converts the initial portion of the string starting at STR (if PTR != NULL)
+   or the entire string starting at STR (if PTR == NULL) to a number of type
+   'long double'.
+   CONVERT should be a conversion function with the same calling conventions
+   as strtold, such as strtold or c_strtold.
+   If successful, it returns true, with *RESULT set to the result.
+   If it fails, it returns false, with *RESULT set to
+     - 0.0L upon conversion error,
+     - ±HUGE_VALL (i.e. ±Infinity) upon overflow,
+     - a value near zero upon underflow (only in implementations which consider
+       underflow to be an error),
+   and _maybe_ errno set as well.
+   In both cases, if PTR != NULL, *PTR is set to point to the character after
+   the parsed number.  */
 bool xstrtold (const char *str, const char **ptr, long double *result,
                long double (*convert) (char const *, char **));