Re: [PATCH] MAX.3, MIN.3: New page (and link page) to document MAX() and MIN()

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hello Paul,

On 5/12/21 11:17 PM, Paul Eggert wrote:
> On 5/12/21 1:43 PM, Alejandro Colomar via Libc-alpha wrote:
> 
>> +If any of the arguments is of a floating-point type,
> 
> "any" -> "either"

Okay.  I thought that either meant XOR, but now I learnt it may also be OR.

> 
>> +these macros shouldn't be used
> 
> That's too strong. It's often OK to use MAX and MIN on floating point
> arguments.

Yup, I changed it a few minutes later.

> 
>> +The arguments may be evaluated more than once,
>> +and their types might be promoted to a common type
>> +if both arguments aren't of the same type.
> 
> This is muddy. It should state clearly that even if A and B are both
> integers, MAX (a, b) might not return their maximum. For example, on a
> typical C platform today, MAX (-1, 2147483648) returns 4294967295 and
> MIN (-1, 2147483648) returns 2147483648.

Hmm, yes, I'll add a BUGS section for this.  Usual arithmetic
conversions and why you should avoid them :)

> 
> Also, the man page shouldn't require the arguments to be evaluated at
> least once. It's possible to implement MAX so that it sometimes doesn't
> evaluate one argument, and the documentation shouldn't preclude such an
> implementation.

In which case they might not be evaluated at all?  I'm curious.
Maybe if one of the arguments is literal NAN and the implementation
raises an exception for it?

> 
> The man page should more specifically mention that although MIN and MAX
> are defined <sys/param.h> on GNU platforms, other platforms define them
> elsewhere or not at all.

Okay.

> 
>> +These macros return the value of one of their arguments,
> 
> Unfortunately they don't necessarily do that, as shown in the MAX
> example above.

Fixed.

> 
> I suggest looking at the remarks about MAX and MIN that are made here,
> and incorporating the useful parts of these remarks into the man page:
> 
> https://git.savannah.gnu.org/cgit/gnulib.git/tree/lib/minmax.h
> 

Okay.

Thank you very much!

Cheers,

Alex

-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/