This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: [PATCH v2 3/6] Document _FloatN and _FloatNx versions of math functions
On Wed, 21 Jun 2017, Gabriel F. T. Gomes wrote:
> +@comment math.h
> +@comment ISO/IEC TS 18661-3
> +@deftypevr Macro _FloatN HUGE_VAL_FN
> +@comment math.h
> +@comment ISO/IEC TS 18661-3
> +@deftypevrx Macro _FloatNx HUGE_VAL_FNx
> +These macros are like @code{HUGE_VAL}, except for the type of the
> +floating-point number that they produce.
> +
> +They were introduced in @w{ISO/IEC TS 18661-3} and are available on
> +machines that support the related types; @pxref{Mathematics}.
> +@end deftypevr
I don't think it's appropriate to have all these duplicated stanzas in the
manual saying the _FloatN / _FloatNx interfaces are like others except for
the type - they should be added to the existing stanzas that already
cover the float, double and long double functions.
I think that you should in this case use @deftypevrx for the new macros,
along with @standardsx to indicate the standards for these interfaces
(*not* @comment as you have there, which is the old syntax). Likewise
@deftypefunx, etc. - and in the cases where text explicitly says something
was added in TS 18661-1, amend that text to say TS 18661-1 and TS 18661-3
(with the expectation that all such sentences will be removed once we
start putting @standards information in the formatted manual).
To avoid losing the information about where the *fN / *fNx functions come
from, the statement about the types being provided ("On some machines,
@theglibc{} also provides...") could be expanded to say how *fN / *fNx
functions are provided, and in general those functions come from TS
18661-3 (then only mention explicitly for a few functions that the *fN /
*fNx functions are GNU extensions).
> +@deftypefun _FloatN fabsfN (_Float@var{N} @var{number})
> +@deftypefunx _FloatNx fabsfNx (_Float@var{N}x @var{number})
> +@standards{TS 18661-3:2015, math.h}
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +These functions are like @code{fabs}, except for the floating-point
> +argument and for the return type.
Apart from what I said above about merging with the existing fabs*
description, note that a bit above there's a statement "@code{fabs},
@code{fabsf} and @code{fabsl} are declared in @file{math.h}. @code{cabs},
@code{cabsf} and @code{cabsl} are declared in @file{complex.h}.". That
needs amending, maybe to say "the @code{fabs} functions" etc. so it
doesn't need all the functions listed explicitly.
--
Joseph S. Myers
joseph@codesourcery.com