Update comments in mpa.c

Fixed comment style and clearer wording in some cases.

1 files changed, 47 insertions, 67 deletions

diff --git a/sysdeps/ieee754/dbl-64/mpa.c b/sysdeps/ieee754/dbl-64/mpa.c
index b0571f9f93..7abad67823 100644
--- a/sysdeps/ieee754/dbl-64/mpa.c
+++ b/sysdeps/ieee754/dbl-64/mpa.c
@@ -45,7 +45,7 @@
 #include "endian.h"
 #include "mpa.h"
 #include "mpa2.h"
-#include <sys/param.h>	/* For MIN() */
+#include <sys/param.h>
 
 #ifndef SECTION
 # define SECTION
@@ -57,10 +57,8 @@ const mp_no mptwo = {1, {1.0, 2.0}};
 #endif
 
 #ifndef NO___ACR
-/* mcr() compares the sizes of the mantissas of two multiple precision  */
-/* numbers. Mantissas are compared regardless of the signs of the       */
-/* numbers, even if x->d[0] or y->d[0] are zero. Exponents are also     */
-/* disregarded.                                                         */
+/* Compare mantissa of two multiple precision numbers regardless of the sign
+   and exponent of the numbers.  */
 static int
 mcr(const mp_no *x, const mp_no *y, int p) {
   int i;
@@ -71,8 +69,7 @@ mcr(const mp_no *x, const mp_no *y, int p) {
   return 0;
 }
 
-
-/* acr() compares the absolute values of two multiple precision numbers */
+/* Compare the absolute values of two multiple precision numbers.  */
 int
 __acr(const mp_no *x, const mp_no *y, int p) {
   int i;
@@ -92,19 +89,18 @@ __acr(const mp_no *x, const mp_no *y, int p) {
 }
 #endif
 
-
 #ifndef NO___CPY
-/* Copy a multiple precision number. Set *y=*x. x=y is permissible.      */
+/* Copy multiple precision number X into Y.  They could be the same
+   number.  */
 void __cpy(const mp_no *x, mp_no *y, int p) {
   EY = EX;
   for (int i=0; i <= p; i++)    Y[i] = X[i];
 }
 #endif
 
-
 #ifndef NO___MP_DBL
-/* Convert a multiple precision number *x into a double precision */
-/* number *y, normalized case  (|x| >= 2**(-1022))) */
+/* Convert a multiple precision number *X into a double precision
+   number *Y, normalized case  (|x| >= 2**(-1022))).  */
 static void norm(const mp_no *x, double *y, int p)
 {
   #define R  RADIXI
@@ -154,8 +150,8 @@ static void norm(const mp_no *x, double *y, int p)
 #undef R
 }
 
-/* Convert a multiple precision number *x into a double precision */
-/* number *y, denormalized case  (|x| < 2**(-1022))) */
+/* Convert a multiple precision number *X into a double precision
+   number *Y, Denormal case  (|x| < 2**(-1022))).  */
 static void denorm(const mp_no *x, double *y, int p)
 {
   int i,k;
@@ -198,9 +194,8 @@ static void denorm(const mp_no *x, double *y, int p)
 #undef R
 }
 
-/* Convert a multiple precision number *x into a double precision number *y. */
-/* The result is correctly rounded to the nearest/even. *x is left unchanged */
-
+/* Convert multiple precision number *X into double precision number *Y.  The
+   result is correctly rounded to the nearest/even.  */
 void __mp_dbl(const mp_no *x, double *y, int p) {
 
   if (X[0] == ZERO)  {*y = ZERO;  return; }
@@ -212,11 +207,8 @@ void __mp_dbl(const mp_no *x, double *y, int p) {
 }
 #endif
 
-
-/* dbl_mp() converts a double precision number x into a multiple precision  */
-/* number *y. If the precision p is too small the result is truncated. x is */
-/* left unchanged.                                                          */
-
+/* Get the multiple precision equivalent of X into *Y.  If the precision is too
+   small, the result is truncated.  */
 void
 SECTION
 __dbl_mp(double x, mp_no *y, int p) {
@@ -224,16 +216,16 @@ __dbl_mp(double x, mp_no *y, int p) {
   int i,n;
   double u;
 
-  /* Sign */
+  /* Sign.  */
   if      (x == ZERO)  {Y[0] = ZERO;  return; }
   else if (x >  ZERO)   Y[0] = ONE;
   else                 {Y[0] = MONE;  x=-x;   }
 
-  /* Exponent */
+  /* Exponent.  */
   for (EY=ONE; x >= RADIX; EY += ONE)   x *= RADIXI;
   for (      ; x <  ONE;   EY -= ONE)   x *= RADIX;
 
-  /* Digits */
+  /* Digits.  */
   n=MIN(p,4);
   for (i=1; i<=n; i++) {
     u = (x + TWO52) - TWO52;
@@ -242,13 +234,10 @@ __dbl_mp(double x, mp_no *y, int p) {
   for (   ; i<=p; i++)     Y[i] = ZERO;
 }
 
-
-/*  add_magnitudes() adds the magnitudes of *x & *y assuming that           */
-/*  abs(*x) >= abs(*y) > 0.                                                 */
-/* The sign of the sum *z is undefined. x&y may overlap but not x&z or y&z. */
-/* No guard digit is used. The result equals the exact sum, truncated.      */
-/* *x & *y are left unchanged.                                              */
-
+/* Add magnitudes of *X and *Y assuming that abs (*X) >= abs (*Y) > 0.  The
+   sign of the sum *Z is not changed.  X and Y may overlap but not X and Z or
+   Y and Z.  No guard digit is used.  The result equals the exact sum,
+   truncated.  */
 static void
 SECTION
 add_magnitudes(const mp_no *x, const mp_no *y, mp_no *z, int p) {
@@ -286,13 +275,10 @@ add_magnitudes(const mp_no *x, const mp_no *y, mp_no *z, int p) {
   else   EZ += ONE;
 }
 
-
-/*  sub_magnitudes() subtracts the magnitudes of *x & *y assuming that      */
-/*  abs(*x) > abs(*y) > 0.                                                  */
-/* The sign of the difference *z is undefined. x&y may overlap but not x&z  */
-/* or y&z. One guard digit is used. The error is less than one ulp.         */
-/* *x & *y are left unchanged.                                              */
-
+/* Subtract the magnitudes of *X and *Y assuming that abs (*x) > abs (*y) > 0.
+   The sign of the difference *Z is not changed.  X and Y may overlap but not X
+   and Z or Y and Z.  One guard digit is used.  The error is less than one
+   ULP.  */
 static void
 SECTION
 sub_magnitudes(const mp_no *x, const mp_no *y, mp_no *z, int p) {
@@ -344,11 +330,9 @@ sub_magnitudes(const mp_no *x, const mp_no *y, mp_no *z, int p) {
     Z[k++] = ZERO;
 }
 
-
-/* Add two multiple precision numbers. Set *z = *x + *y. x&y may overlap  */
-/* but not x&z or y&z. One guard digit is used. The error is less than    */
-/* one ulp. *x & *y are left unchanged.                                   */
-
+/* Add *X and *Y and store the result in *Z.  X and Y may overlap, but not X
+   and Z or Y and Z.  One guard digit is used.  The error is less than one
+   ULP.  */
 void
 SECTION
 __add(const mp_no *x, const mp_no *y, mp_no *z, int p) {
@@ -369,11 +353,9 @@ __add(const mp_no *x, const mp_no *y, mp_no *z, int p) {
   }
 }
 
-
-/* Subtract two multiple precision numbers. *z is set to *x - *y. x&y may */
-/* overlap but not x&z or y&z. One guard digit is used. The error is      */
-/* less than one ulp. *x & *y are left unchanged.                         */
-
+/* Subtract *Y from *X and return the result in *Z.  X and Y may overlap but
+   not X and Z or Y and Z.  One guard digit is used.  The error is less than
+   one ULP.  */
 void
 SECTION
 __sub(const mp_no *x, const mp_no *y, mp_no *z, int p) {
@@ -394,12 +376,9 @@ __sub(const mp_no *x, const mp_no *y, mp_no *z, int p) {
   }
 }
 
-
-/* Multiply two multiple precision numbers. *z is set to *x * *y. x&y      */
-/* may overlap but not x&z or y&z. In case p=1,2,3 the exact result is     */
-/* truncated to p digits. In case p>3 the error is bounded by 1.001 ulp.   */
-/* *x & *y are left unchanged.                                             */
-
+/* Multiply *X and *Y and store result in *Z.  X and Y may overlap but not X
+   and Z or Y and Z.  For P in [1, 2, 3], the exact result is truncated to P
+   digits.  In case P > 3 the error is bounded by 1.001 ULP.  */
 void
 SECTION
 __mul(const mp_no *x, const mp_no *y, mp_no *z, int p) {
@@ -414,7 +393,7 @@ __mul(const mp_no *x, const mp_no *y, mp_no *z, int p) {
       return;
     }
 
-  /* Multiply, add and carry */
+  /* Multiply, add and carry.  */
   k2 = (__glibc_unlikely (p < 3)) ? p + p : p + 3;
   Z[k2] = ZERO;
 
@@ -443,7 +422,7 @@ __mul(const mp_no *x, const mp_no *y, mp_no *z, int p) {
     }
 
   EZ = EX + EY;
-  /* Is there a carry beyond the most significant digit? */
+  /* Is there a carry beyond the most significant digit?  */
   if (__glibc_unlikely (Z[1] == ZERO))
     {
       for (i = 1; i <= p; i++)
@@ -454,12 +433,12 @@ __mul(const mp_no *x, const mp_no *y, mp_no *z, int p) {
   Z[0] = X[0] * Y[0];
 }
 
+/* Invert *X and store in *Y.  Relative error bound:
+   - For P = 2: 1.001 * R ^ (1 - P)
+   - For P = 3: 1.063 * R ^ (1 - P)
+   - For P > 3: 2.001 * R ^ (1 - P)
 
-/* Invert a multiple precision number. Set *y = 1 / *x.                     */
-/* Relative error bound = 1.001*r**(1-p) for p=2, 1.063*r**(1-p) for p=3,   */
-/* 2.001*r**(1-p) for p>3.                                                  */
-/* *x=0 is not permissible. *x is left unchanged.                           */
-
+   *X = 0 is not permissible.  */
 static
 SECTION
 void __inv(const mp_no *x, mp_no *y, int p) {
@@ -480,12 +459,13 @@ void __inv(const mp_no *x, mp_no *y, int p) {
   }
 }
 
+/* Divide *X by *Y and store result in *Z.  X and Y may overlap but not X and Z
+   or Y and Z.  Relative error bound:
+   - For P = 2: 2.001 * R ^ (1 - P)
+   - For P = 3: 2.063 * R ^ (1 - P)
+   - For P > 3: 3.001 * R ^ (1 - P)
 
-/* Divide one multiple precision number by another.Set *z = *x / *y. *x & *y */
-/* are left unchanged. x&y may overlap but not x&z or y&z.                   */
-/* Relative error bound = 2.001*r**(1-p) for p=2, 2.063*r**(1-p) for p=3     */
-/* and 3.001*r**(1-p) for p>3. *y=0 is not permissible.                      */
-
+   *X = 0 is not permissible.  */
 void
 SECTION
 __dvd(const mp_no *x, const mp_no *y, mp_no *z, int p) {