propagate from branch 'net.randombit.botan' (head 294e2082ce9231d6165276e2f2a4153a0116aca3)

            to branch 'net.randombit.botan.c++0x' (head 0b695fad10f924601e07b009fcd781191fafcb28)

5 files changed, 77 insertions, 20 deletions

diff --git a/src/math/numbertheory/def_powm.h b/src/math/numbertheory/def_powm.h
index 5b8a5a591..ce128b965 100644
--- a/src/math/numbertheory/def_powm.h
+++ b/src/math/numbertheory/def_powm.h
@@ -14,7 +14,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Fixed Window Exponentiator
 */
 class Fixed_Window_Exponentiator : public Modular_Exponentiator
@@ -36,7 +36,7 @@ class Fixed_Window_Exponentiator : public Modular_Exponentiator
       Power_Mod::Usage_Hints hints;
    };
 
-/*
+/**
 * Montgomery Exponentiator
 */
 class Montgomery_Exponentiator : public Modular_Exponentiator
diff --git a/src/math/numbertheory/numthry.h b/src/math/numbertheory/numthry.h
index 2d889a68a..9a1005413 100644
--- a/src/math/numbertheory/numthry.h
+++ b/src/math/numbertheory/numthry.h
@@ -14,8 +14,8 @@
 
 namespace Botan {
 
-/*
-* Fused Arithmetic Operations
+/**
+* Fused Arithmetic Operation
 */
 BigInt BOTAN_DLL mul_add(const BigInt&, const BigInt&, const BigInt&);
 BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&);
@@ -25,27 +25,70 @@ BigInt BOTAN_DLL sub_mul(const BigInt&, const BigInt&, const BigInt&);
 */
 inline BigInt abs(const BigInt& n) { return n.abs(); }
 
-void BOTAN_DLL divide(const BigInt&, const BigInt&, BigInt&, BigInt&);
-
+/**
+* Compute the greatest common divisor
+* @param x a positive integer
+* @param y a positive integer
+* @return gcd(x,y)
+*/
 BigInt BOTAN_DLL gcd(const BigInt& x, const BigInt& y);
+
+/**
+* Least common multiple
+* @param x a positive integer
+* @param y a positive integer
+* @return z, smallest integer such that z % x == 0 and z % y == 0
+*/
 BigInt BOTAN_DLL lcm(const BigInt& x, const BigInt& y);
 
-BigInt BOTAN_DLL square(const BigInt&);
-BigInt BOTAN_DLL inverse_mod(const BigInt&, const BigInt&);
-s32bit BOTAN_DLL jacobi(const BigInt&, const BigInt&);
+/**
+* @param x an integer
+* @return (x*x)
+*/
+BigInt BOTAN_DLL square(const BigInt& x);
+
+/**
+* Modular inversion
+* @param x a positive integer
+* @param modulus a positive integer
+* @return y st (x*y) % modulus == 1
+*/
+BigInt BOTAN_DLL inverse_mod(const BigInt& x,
+                             const BigInt& modulus);
 
+/**
+* Compute the Jacobi symbol. If n is prime, this is equivalent
+* to the Legendre symbol.
+* @see http://mathworld.wolfram.com/JacobiSymbol.html
+*
+* @param a is a non-negative integer
+* @param n is an odd integer > 1
+* @return (n / m)
+*/
+s32bit BOTAN_DLL jacobi(const BigInt& a,
+                        const BigInt& n);
+
+/**
+* Modular exponentation
+*/
 BigInt BOTAN_DLL power_mod(const BigInt&, const BigInt&, const BigInt&);
 
-/*
-* Compute the square root of x modulo a prime
-* using the Shanks-Tonnelli algorithm
+/**
+* Compute the square root of x modulo a prime using the
+* Shanks-Tonnelli algorithm
+*
+* @param x the input
+* @param p the prime
+* @return y such that (y*y)%p == x, or -1 if no such integer
 */
 BigInt BOTAN_DLL ressol(const BigInt& x, const BigInt& p);
 
-/*
-* Utility Functions
+/**
+* @param x an integer
+* @return count of the zero bits in x, or, equivalently, the largest
+* value of n such that 2^n divides x evently
 */
-u32bit BOTAN_DLL low_zero_bits(const BigInt&);
+u32bit BOTAN_DLL low_zero_bits(const BigInt& x);
 
 /*
 * Primality Testing
diff --git a/src/math/numbertheory/point_gfp.h b/src/math/numbertheory/point_gfp.h
index 0708493fe..5b3e32c7d 100644
--- a/src/math/numbertheory/point_gfp.h
+++ b/src/math/numbertheory/point_gfp.h
@@ -15,6 +15,10 @@
 
 namespace Botan {
 
+/**
+* Exception thrown if you try to convert a zero point to an affine
+* coordinate
+*/
 struct BOTAN_DLL Illegal_Transformation : public Exception
    {
    Illegal_Transformation(const std::string& err =
@@ -22,6 +26,9 @@ struct BOTAN_DLL Illegal_Transformation : public Exception
       Exception(err) {}
    };
 
+/**
+* Exception thrown if some form of illegal point is decoded
+*/
 struct BOTAN_DLL Illegal_Point : public Exception
    {
    Illegal_Point(const std::string& err = "Malformed ECP point detected") :
diff --git a/src/math/numbertheory/pow_mod.h b/src/math/numbertheory/pow_mod.h
index 7b92f0ec4..1a60ca05f 100644
--- a/src/math/numbertheory/pow_mod.h
+++ b/src/math/numbertheory/pow_mod.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Modular Exponentiator Interface
 */
 class BOTAN_DLL Modular_Exponentiator
@@ -25,7 +25,7 @@ class BOTAN_DLL Modular_Exponentiator
       virtual ~Modular_Exponentiator() {}
    };
 
-/*
+/**
 * Modular Exponentiator Proxy
 */
 class BOTAN_DLL Power_Mod
@@ -67,7 +67,7 @@ class BOTAN_DLL Power_Mod
       Usage_Hints hints;
    };
 
-/*
+/**
 * Fixed Exponent Modular Exponentiator Proxy
 */
 class BOTAN_DLL Fixed_Exponent_Power_Mod : public Power_Mod
@@ -81,7 +81,7 @@ class BOTAN_DLL Fixed_Exponent_Power_Mod : public Power_Mod
                                Usage_Hints = NO_HINTS);
    };
 
-/*
+/**
 * Fixed Base Modular Exponentiator Proxy
 */
 class BOTAN_DLL Fixed_Base_Power_Mod : public Power_Mod
diff --git a/src/math/numbertheory/reducer.h b/src/math/numbertheory/reducer.h
index c121f1499..861983ef0 100644
--- a/src/math/numbertheory/reducer.h
+++ b/src/math/numbertheory/reducer.h
@@ -12,7 +12,7 @@
 
 namespace Botan {
 
-/*
+/**
 * Modular Reducer
 */
 class BOTAN_DLL Modular_Reducer
@@ -24,18 +24,25 @@ class BOTAN_DLL Modular_Reducer
 
       /**
       * Multiply mod p
+      * @param x
+      * @param y
+      * @return (x * y) % p
       */
       BigInt multiply(const BigInt& x, const BigInt& y) const
          { return reduce(x * y); }
 
       /**
       * Square mod p
+      * @param x
+      * @return (x * x) % p
       */
       BigInt square(const BigInt& x) const
          { return reduce(Botan::square(x)); }
 
       /**
       * Cube mod p
+      * @param x
+      * @return (x * x * x) % p
       */
       BigInt cube(const BigInt& x) const
          { return multiply(x, this->square(x)); }