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] Add nextup and nextdown math functions


> diff --git a/manual/arith.texi b/manual/arith.texi
> index 72682f0..a869922 100644
> --- a/manual/arith.texi
> +++ b/manual/arith.texi
> @@ -1687,6 +1687,25 @@ This function is defined in @w{IEC 559} (and the appendix with
>  recommended functions in @w{IEEE 754}/@w{IEEE 854}).
>  @end deftypefun
>  
> +
> +@comment math.h
> +@comment GNU
> +@deftypefun double nextdown (double @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx float nextdownf (float @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx {long double} nextdownl (long double @var{x})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +The @code{nextdown} function returns the next representable value
> +less than @var{x}. If @var{x} is the positive number of least
> +magnitude the function returns +0. If @var{x} is zero, the function returns
> +the negative number of least magnitude in the type of @var{x}.

Is +0 not considered a positive number?

The manual is all over the place with this, but there is a strong
tendency to wrap numbers, esp. where they're return values and such, in
@code{}, so "returns @code{+0}."  @math{} is also used for formatting
numbers, but not nearly as widely.

Similar question for -0, and whether it is considered a negative number.
 Also, does zero in "If @var{x} is zero" imply all of -0, 0, and +0?

> +nextdown(@code{-HUGE_VAL}) is @code{-HUGE_VAL}. It is based on draft

I can't recall ever seeing a function call within a paragraph, and
haven't been able to find an example, skimming through the manual.  I
suggest using a similar style to what you've already used (i.e., "If
@var{x} is @code{-HUGE_VAL}, the return value is @code{-HUGE_VAL}.") or
breaking it out into a @smallexample and rearranging/rewording as necessary.

There is a good flow here, though: I found myself asking what happens if
you have the lowest number once the zero case was mentioned, and then
you answered it right away.  :)

I think changing "It" to @code{nextdown} would be nice; it feels like
it's somehow talking about HUGE_VAL, or specifically that aforementioned
outcome.  Also, it will be necessary if you change the subject of the
HUGE_VAL sentence to x or move it to its own paragraph following a
@smallexample.

> +TS 18661 and currently enabled as a GNU extension.
> +@end deftypefun
> +
>  @comment math.h
>  @comment ISO
>  @deftypefun double nexttoward (double @var{x}, long double @var{y})
> @@ -1702,6 +1721,25 @@ These functions are identical to the corresponding versions of

Is there a reason you split these new descriptions apart across
nexttoward? nextafter and nexttoward are related to each other, and
nextup and nextdown are also their own pair.

>  double}.
>  @end deftypefun
>  
> +@comment math.h
> +@comment GNU
> +@deftypefun double nextup (double @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx float nextupf (float @var{x})
> +@comment math.h
> +@comment GNU
> +@deftypefunx {long double} nextupl (long double @var{x})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
> +
> +The @code{nextup} function returns the next representable value
> +greater than @var{x}. If @var{x} is the negative number of least
> +magnitude the function returns -0. If @var{x} is zero, the function returns
> +the positive number of least magnitude in the type of @var{x}.
> +nextup(@code{HUGE_VAL}) is @code{HUGE_VAL}. It is based on draft
> +TS 18661 and currently enabled as a GNU extension.
> +@end deftypefun
> +
>  @cindex NaN
>  @comment math.h
>  @comment ISO

Same comments/questions on nextup as nextdown.

Thanks for documenting your work on the new stuff!

Rical


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