libm: improve readability of math.h; expand comments and docs

Signed-off-by: Denys Vlasenko <vda.linux@googlemail.com>

docs/defines.txt

@@ -16,11 +16,18 @@ _LARGEFILE[64]_SOURCE
 _FILE_OFFSET_BITS
     ???
 
-__NTH(fct)
 __THROW
-__REDIRECT(name, proto, alias)
-__REDIRECT_NTH(name, proto, alias)
-    ???
+    Function annotation "I do not throw anything".
+__NTH(func(params))
+    Function annotation "I do not throw anything".
+    Needed for situatuons when it's unclear on what side of "func(params)"
+    the "throw()" or "attribute((nothrow))" should eventually appear.
+    Messy, eh?
+
+return_type __REDIRECT(name, (params), alias)
+    declare alias to "name(params)"
+return_type __REDIRECT_NTH(name, (params), alias)
+    declare alias to "name(params) __THROW"
 
 __BIG_ENDIAN    4321
 __LITTLE_ENDIAN 1234
@@ -49,6 +56,7 @@ _EXTERN_INLINE
 __extern_inline
     Defined to "extern inline", modulo gcc/C standard deviations.
     Can't be used by user to play tricks as with _EXTERN_INLINE.
+
 internal_function
     Used to modify function's calling convention, if "standard" one
     is suboptimal. Examples:

include/complex.h

@@ -54,13 +54,13 @@ __BEGIN_DECLS
    so we can easily declare each function as both `name' and `__name',
    and can declare the float versions `namef' and `__namef'.  */
 
-#define __MATHCALL(function, args)	\
-  __MATHDECL (_Mdouble_complex_,function, args)
+#define __MATHCALL(function, args) \
+	__MATHDECL(_Mdouble_complex_,function, args)
 #define __MATHDECL(type, function, args) \
-  __MATHDECL_1(type, function, args); \
-  __MATHDECL_1(type, __CONCAT(__,function), args)
+	__MATHDECL_1(type, function, args); \
+	__MATHDECL_1(type, __CONCAT(__,function), args)
 #define __MATHDECL_1(type, function, args) \
-  extern type __MATH_PRECNAME(function) args __THROW
+	extern type __MATH_PRECNAME(function) args __THROW
 
 #define _Mdouble_		double
 #define __MATH_PRECNAME(name)	name

include/math.h

@@ -53,40 +53,40 @@ __BEGIN_DECLS
    and can declare the float versions `namef' and `__namef'.  */
 
 #define __MATHDECL_1(type,function,suffix,args) \
-  extern type __MATH_PRECNAME(function,suffix) args __THROW
+	extern type __MATH_PRECNAME(function,suffix) args __THROW
 
 #define __MATHDECL(type,function,suffix,args) \
-  __MATHDECL_1(type,function,suffix,args);
+	__MATHDECL_1(type,function,suffix,args);
 
-#define __MATHCALL(function,suffix,args)	\
-  __MATHDECL(_Mdouble_,function,suffix,args)
+#define __MATHCALL(function,suffix,args) \
+	__MATHDECL(_Mdouble_,function,suffix,args)
 
 #define __MATHDECLX(type,function,suffix,args,attrib) \
-  __MATHDECL_1(type,function,suffix,args) __attribute__ (attrib); \
-  __MATH_maybe_libm_hidden_proto(function)
+	__MATHDECL_1(type,function,suffix,args) __attribute__ (attrib); \
+	__MATH_maybe_libm_hidden_proto(function)
 
-#define __MATHCALLX(function,suffix,args,attrib)	\
-  __MATHDECLX(_Mdouble_,function,suffix,args,attrib)
+#define __MATHCALLX(function,suffix,args,attrib) \
+	__MATHDECLX(_Mdouble_,function,suffix,args,attrib)
 
 /* Decls which are also used internally in libm.
    Only the main variant is used internally, no need to try to avoid relocs
    for the {l,f} variants.  */
 #define __MATHDECLI(type,function,suffix,args) \
-  __MATHDECL_1(type,function,suffix,args); \
-  __MATH_maybe_libm_hidden_proto(function)
+	__MATHDECL_1(type,function,suffix,args); \
+	__MATH_maybe_libm_hidden_proto(function)
 
-#define __MATHCALLI(function,suffix,args)	\
-  __MATHDECLI(_Mdouble_,function,suffix,args)
+#define __MATHCALLI(function,suffix,args) \
+	__MATHDECLI(_Mdouble_,function,suffix,args)
 
 /* Private helpers for purely macro impls below.
    Only make __foo{,f,l} visible but not (the macro-only) foo.  */
 #if defined _LIBC
 # define __MATHDECL_PRIV(type,function,suffix,args,attrib) \
-  __MATHDECL_1(type,__CONCAT(__,function),suffix,args) __attribute__ (attrib); \
-  libm_hidden_proto(__MATH_PRECNAME(__##function,suffix))
+	__MATHDECL_1(type,__CONCAT(__,function),suffix,args) __attribute__ (attrib); \
+	libm_hidden_proto(__MATH_PRECNAME(__##function,suffix))
 #else
 # define __MATHDECL_PRIV(type,function,suffix,args,attrib) \
-  __MATHDECL_1(type,__CONCAT(__,function),suffix,args) __attribute__ (attrib);
+	__MATHDECL_1(type,__CONCAT(__,function),suffix,args) __attribute__ (attrib);
 #endif
 
 
@@ -139,17 +139,15 @@ __BEGIN_DECLS
 #  ifdef __LDBL_COMPAT
 
 #   ifdef __USE_ISOC99
-extern float __nldbl_nexttowardf (float __x, long double __y)
-				  __THROW __attribute__ ((__const__));
+extern float __nldbl_nexttowardf (float __x, long double __y) __THROW
+			__attribute__ ((__const__));
 #    ifdef __REDIRECT_NTH
-extern float __REDIRECT_NTH (nexttowardf, (float __x, long double __y),
-			     __nldbl_nexttowardf)
-     __attribute__ ((__const__));
-extern double __REDIRECT_NTH (nexttoward, (double __x, long double __y),
-			      nextafter) __attribute__ ((__const__));
-extern long double __REDIRECT_NTH (nexttowardl,
-				   (long double __x, long double __y),
-				   nextafter) __attribute__ ((__const__));
+extern float __REDIRECT_NTH (nexttowardf, (float __x, long double __y), __nldbl_nexttowardf)
+			__attribute__ ((__const__));
+extern double __REDIRECT_NTH (nexttoward, (double __x, long double __y), nextafter)
+			__attribute__ ((__const__));
+extern long double __REDIRECT_NTH (nexttowardl, (long double __x, long double __y), nextafter)
+			__attribute__ ((__const__));
 #    endif
 #   endif
 
@@ -158,9 +156,9 @@ extern long double __REDIRECT_NTH (nexttowardl,
 
 #   undef __MATHDECL_1
 #   define __MATHDECL_2(type,function,suffix,args,alias) \
-  extern type __REDIRECT_NTH(__MATH_PRECNAME(function,suffix),args,alias)
+	extern type __REDIRECT_NTH(__MATH_PRECNAME(function,suffix),args,alias)
 #   define __MATHDECL_1(type,function,suffix,args) \
-  __MATHDECL_2(type,function,suffix,args,__CONCAT(function,suffix))
+	__MATHDECL_2(type,function,suffix,args,__CONCAT(function,suffix))
 #  endif
 
 #  define __MATH_maybe_libm_hidden_proto(x)

libc/sysdeps/linux/alpha/bits/mathdef.h

@@ -44,12 +44,12 @@ typedef double double_t;
 /* Due to an ABI change, we need to remap the complex float symbols.  */
 #  define _Mdouble_		float
 #  define __MATHCALL(function, args) \
-    __MATHDECL (_Complex float, function, args)
+	__MATHDECL(_Complex float, function, args)
 #  define __MATHDECL(type, function, args) \
-    __MATHDECL_1(type, function##f, args, __c1_##function##f); \
-    __MATHDECL_1(type, __##function##f, args, __c1_##function##f)
+	__MATHDECL_1(type, function##f, args, __c1_##function##f); \
+	__MATHDECL_1(type, __##function##f, args, __c1_##function##f)
 #  define __MATHDECL_1(type, function, args, alias) \
-    extern type function args __asm__(#alias) __THROW
+	extern type function args __asm__(#alias) __THROW
 
 #  include <bits/cmathcalls.h>
 

libc/sysdeps/linux/common/bits/mathcalls.h

@@ -48,11 +48,16 @@
 #endif
 
 
-/* __MATHCALLX and __MATHCALLI include libm_hidden_def
+/* __MATHCALLX(type,function,[suffix],args,attrib) and
+ * __MATHCALLI(type,function,[suffix],args) include libm_hidden_def
  * (for "double" versions only, xxxf and xxxl do not get this treatment).
- * __MATHCALL does not.
- * __MATHDECL_PRIV includes libm_hidden_def (always)
- * and declares __foo, not foo.
+ *
+ * __MATHDECL(type,function,[suffix],args) does not.
+ * __MATHCALL(function,[suffix],args) also does not
+ * (it is just a shortcut to __MATHDECL(_Mdouble_,function,[suffix],args)).
+ *
+ * __MATHDECL_PRIV(type,function,[suffix],args,attrib)
+ * includes libm_hidden_def (always) and declares __foo, not foo.
  */
 
 

libc/sysdeps/linux/i386/bits/mathinline.h

@@ -206,7 +206,7 @@ __NTH (__signbitl (long double __x))
   __MATH_INLINE float_type __NTH (func (float_type __x))		      \
   {									      \
     register float_type __result;					      \
-    __asm__ __volatile__ (op : "=t" (__result) : params);			      \
+    __asm__ __volatile__ (op : "=t" (__result) : params);		      \
     return __result;							      \
   }