[PATCH] Improve __LONG_DOUBLE_USES_FLOAT128 commentary

[Joseph Myers]

On Fri, 14 Feb 2020, Paul E. Murphy wrote:

> +/* The macro __LONG_DOUBLE_USES_FLOAT128 is used to determine the
> +   choice of the underlying ABI of long double during a single compilation.
> +
> +   If the value is non-zero, any API which is parameterized by the long
> +   double type (i.e the scanf/printf family of functions or the explicitly
> +   parameterized math.h functions) will be redirected to a compatible
> +   implementation using _Float128 ABI via symbols suffixed with ieee128.
> +
> +   These redirections usually take the form of an "ASM Label" as called out
> +   int Chapter 6.47.4 in the GCC 9 manual.  And in very rare cases, a
> +   macro.  They do not alter or otherwise change the ABI stability of glibc.

I don't think this paragraph about how the redirections are implemented 
should be present at all; it's simply a description of how the redirection 
macros work, which belongs with the implementation of those macros if 
anywhere.  (And referencing particular section numbers in the GCC manual 
is a bad idea; section names may be somewhat stable, numbers are very 
unstable.)

> diff --git a/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h b/sysdeps/ieee754/ldbl-128ibm-compat/bits/long-double.h

I think it's best for the detailed comment defining the semantics of the 
macro to be only in the default bits/long-double.h file, with 
architecture-specific files having comments that only discuss the 
architecture-specific details for that architecture.  That avoids having 
multiple places that need updating with any improvement to the 
documentation.

-- 
Joseph S. Myers
joseph@codesourcery.com