Re: [PATCH v3 2/2] float128: Add strfromf128, strtof128, and wcstof128 to the manual

[Rical Jasan <ricaljasan at pacific dot net>]

On 06/07/2017 02:35 PM, Gabriel F. T. Gomes wrote:
> diff --git a/manual/arith.texi b/manual/arith.texi
> index dec12a0..1f13769 100644
> --- a/manual/arith.texi
> +++ b/manual/arith.texi
> @@ -2990,23 +2990,45 @@ double} is a separate type).
>  These functions have been GNU extensions and are new to @w{ISO C99}.
>  @end deftypefun
>  
> +@comment stdlib.h
> +@comment ISO/IEC TS 18661-3
> +@deftypefun _FloatN strtofN (const char *@var{string}, char **@var{tailptr})
> +@deftypefunx _FloatNx strtofN (const char *@var{string}, char **@var{tailptr})

Both @defs should have @comments.

The second @def should be strtofNx.

> +@safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}

See thoughts on safety comments below.

> +These functions are like @code{strtod}, except for the return type.
> +
> +They were introduced in @w{ISO/IEC TS 18661-3} and are available on machines
> +that support the related types, as described in @ref{Mathematics}.

"that support the related types; @pxref{Mathematics}."

@ref should almost never be used, because it doesn't render correctly
across all the documentation types.

> +@end deftypefun
> +
>  @comment wchar.h
>  @comment ISO
>  @deftypefun double wcstod (const wchar_t *restrict @var{string}, wchar_t **restrict @var{tailptr})
> -@comment stdlib.h
> +@comment wchar.h
>  @comment ISO
>  @deftypefunx float wcstof (const wchar_t *@var{string}, wchar_t **@var{tailptr})
> -@comment stdlib.h
> +@comment wchar.h
>  @comment ISO
>  @deftypefunx {long double} wcstold (const wchar_t *@var{string}, wchar_t **@var{tailptr})

Thanks for fixing.

> +@comment wchar.h
> +@deftypefunx _FloatN wcstofN (const wchar_t *@var{string}, wchar_t **@var{tailptr})

Needs a standard.  "@comment GNU" should be correct if this is a GNU
extension.

> +@deftypefunx _FloatNx wcstofNx (const wchar_t *@var{string}, wchar_t **@var{tailptr})

This should have its own header and standard @comments.

>  @safety{@prelim{}@mtsafe{@mtslocale{}}@assafe{}@acsafe{}}

See thoughts on safety comments below.

> -The @code{wcstod}, @code{wcstof}, and @code{wcstol} functions are
> -equivalent in nearly all aspect to the @code{strtod}, @code{strtof}, and
> -@code{strtold} functions but it handles wide character string.
> +The @code{wcstod}, @code{wcstof}, @code{wcstol}, @code{wcstof@var{N}},
> +and @code{wcstof@var{N}x} functions are equivalent in nearly all aspect

aspects (while you're at it)

> +to the @code{strtod}, @code{strtof}, @code{strtold},
> +@code{strtof@var{N}}, and @code{strtof@var{N}x} functions but they

I would put a comma after "functions", since there's a natural pause.

> +handle wide character strings.
>  
>  The @code{wcstod} function was introduced in @w{Amendment 1} of @w{ISO
>  C90}.  The @code{wcstof} and @code{wcstold} functions were introduced in
>  @w{ISO C99}.
> +
> +The @code{wcstof@var{N}} and @code{wcstof@var{N}x} functions are not in
> +any standard, but are added to provide completeness for the
> +non-deprecated interface of wide character string to floating-point
> +conversion function.  They are only available on machines that support

functions

> +the related types as described in @ref{Mathematics}.

@pxref

>  @end deftypefun
>  
>  @comment stdlib.h
> @@ -3064,6 +3086,19 @@ has been completely written if and only if the returned value is less than
>  These functions were introduced by ISO/IEC TS 18661-1.
>  @end deftypefun
>  
> +@comment stdlib.h
> +@comment ISO/IEC TS 18661-3
> +@deftypefun int strfromfN (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N} @var{value})
> +@deftypefunx int strfromfNx (char *restrict @var{string}, size_t @var{size}, const char *restrict @var{format}, _Float@var{N}x @var{value})

@comments for both @defs.

> +@safety{@prelim{}@mtsafe{@mtslocale{}}@asunsafe{@ascuheap{}}@acunsafe{@acsmem{}}}
> +@comment this function depends on __printf_fp and __printf_fphex, which are
> +@comment AS-unsafe (ascuheap) and AC-unsafe (acsmem).

Not that it matters, but @c tends to be used for these comments.  In
light of the @errno and @standards work I've been doing, I wonder if
that's a historical habit due to external processes utilizing @comments
for various purposes...  but I like the shorter syntax anyway.

It looks like the strfrom's were a rare exception, which I'm guessing
was the template (unseen here, directly above).

At any rate, "this function depends" should be "these functions depend",
if the @safety annotation is true for both of them.  Some of the safety
commentary gets pretty detailed too, so this might be improved by being
more explicit about which function depends on what and where the safety
issues lie; i.e., something like: "strfromfN depends on __printf_fp and
strfromfNx depends on __printf_fphex, both of which are AS-unsafe
(ascuheap) and AC-unsafe (acsmem)."  (I don't actually know if that's
right, just inferring.)

Looking at other safety comments in this file, the locale safety seems
to be an interesting issue ("unsafe-but-ruled-safe").  Maybe a reference
in the comment to more detailed comments would be good ("see safety
comments for strtod", or whatever's appropriate).  This would apply to
the other added functions in this patch too.

> +These functions are like @code{strfromd}, except for the type of @var{value}.

@code{value}, since you're referring to the variable.

> +
> +They were introduced in @w{ISO/IEC TS 18661-3} and are available on machines
> +that support the related types, as described in @ref{Mathematics}.

@pxref

> +@end deftypefun
> +
>  @node System V Number Conversion
>  @section Old-fashioned System V number-to-string functions
>  
> diff --git a/manual/math.texi b/manual/math.texi
> index 69a0ace..a335917 100644
> --- a/manual/math.texi
> +++ b/manual/math.texi
> @@ -53,6 +53,17 @@ usually wise to pick the narrowest type that can accommodate your data.
>  Not all machines have a distinct @code{long double} type; it may be the
>  same as @code{double}.
>  
> +On some machines, @theglibc{} also provides @code{_Float@var{N}} and
> +@code{_Float@var{N}x} types.  These types are defined in @w{ISO/IEC
> +18661-3}, which extends @w{ISO C} and defines floating-point types that

Inconsistent standard name.  "ISO/IEC TS 18661-3" is used everywhere
else (in this patch).

> +are not machine-dependent.  When such a type, e.g.  @code{_Float128}, is

I always put a comma after "e.g.", though that might be a regional
preference.  It looks like the formatting sees it as the end of a
sentence, however (two spaces), and that might impact the rendering.
What about: "When a type such as @code{_Float128} is..."

> +supported by @theglibc{}, extra variants for most of the mathematical
> +functions provided for @code{double}, @code{float}, and @code{long
> +double} are also provided for the supported type.
> +
> +Currently, support for @code{_Float@var{N}} or @code{_Float@var{N}x}
> +types is not provided for any machine.

This is dated already, and it's not even out-of-date.  Can anybody think
of a decent way to keep it up-to-date?  "@c FIXME SOMEDAY" (perhaps with
a liberal dose of exclamation points)?  I'm torn, because actually
dating it (putting the year in there or something) is still prone to the
same problem, but could help readers in 20 years recognize it as
possibly no longer true.

I'd also like to draw attention to the very first line of this patch,
which uses "new" and "ISO C99" in the same breath.

It seems important to say this, though, somehow.  Is there somewhere we
can document support for these types on various machines (or already do,
perhaps for types in general)?  We could then reference it, and it might
be easier for the group mind to remember to keep that current.

> +
>  @menu
>  * Mathematical Constants::      Precise numeric values for often-used
>                                   constants.

Rical