This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]