Add some lightweight documentation.

src/signed/base.rs

@@ -7,6 +7,10 @@ macro_rules! signed_impls {
         }
 
         impl $sname {
+            /// Generate a new signed number from an unsigned number and a
+            /// boolean describing whether or not the new number is negative.
+            /// Note that if the value is zero, the value of the negative flag
+            /// will be ignored.
             pub fn new(negative: bool, value: $name) -> $sname {
                 if value.is_zero() {
                     $sname{ negative: false, value: value }
@@ -15,6 +19,7 @@ macro_rules! signed_impls {
                 }
             }
 
+            /// Return a new number that is the negated version of this number.
             pub fn negate(&self) -> $sname {
                 if self.value.is_zero() {
                     self.clone()
@@ -23,10 +28,12 @@ macro_rules! signed_impls {
                 }
             }
 
+            /// Return the absolute value of the number.
             pub fn abs(&self) -> $sname {
                 $sname{ negative: false, value: self.value.clone() }
             }
 
+            /// Return true iff the value is negative and not zero.
             pub fn is_negative(&self) -> bool {
                 self.negative
             }

src/signed/egcd.rs

@@ -1,4 +1,8 @@
+/// GCD computations, with extended information
 pub trait EGCD<T> {
+    /// Compute the extended GCD for this value and the given value.
+    /// If the inputs to this function are x (self) and y (the argument),
+    /// and the results are (a, b, g), then (a * x) + (b * y) = g.
     fn egcd(&self, rhs: &Self) -> (T, T, T);
 }
 

src/signed/mod.rs

@@ -1,3 +1,14 @@
+//! This module includes a large number of signed integer types for very
+//! large integers, designed to try to match good performance with a high
+//! assurance threshold.
+//! 
+//! The types provided in this module, and the functions available for each
+//! of those types, is derived from standard bit widths for RSA, DSA, and
+//! Elliptic Curve encryption schemes. If this library does not include a
+//! function you would like for another cryptographic scheme, please reach
+//! out to the authors; in many cases, the relevant code can be automatically
+//! generated.
+//! 
 #[macro_use]
 mod add;
 #[macro_use]

src/signed/modinv.rs

@@ -1,4 +1,8 @@
+/// Computations of the modular inverse.
 pub trait ModInv: Sized {
+    /// Compute the modular inverse of this number under the given
+    /// modulus, if it exists. If self is a, the modulus / argument
+    /// is phi, and the result is Some(m), then (a * m) % phi = 1.
     fn modinv(&self, phi: &Self) -> Option<Self>;
 }
 

src/unsigned/barrett.rs

@@ -7,6 +7,9 @@ macro_rules! barrett_impl {
        }
 
        impl $bar {
+           /// Generate a new Barrett number from the given input. This operation
+           /// is relatively slow, so you should only do it if you plan to use 
+           /// reduce() multiple times with the ame number.
            pub fn new(m: $name) -> $bar {
                // Step #1: Figure out k
                let mut k = 0;
@@ -28,6 +31,8 @@ macro_rules! barrett_impl {
                $bar { k: k, m: resm, mu: mu }
            }
 
+           // Reduce the input by this value; in other words, perform a mod
+           // operation.
            pub fn reduce(&self, x: &$dbl) -> $name {
                // 1. q1←⌊x/bk−1⌋, q2←q1 · μ, q3←⌊q2/bk+1⌋.
                let     q1: $name64 = $name64::from(x >> ((self.k - 1) * 64));
@@ -58,6 +63,7 @@ macro_rules! barrett_impl {
        }
 
        impl $name {
+           /// Generate a Barrett number from this number.
            pub fn generate_barrett(&self) -> $bar {
                $bar::new(self.clone())
            }

src/unsigned/base.rs

@@ -1,8 +1,15 @@
+/// A trait definition for large numbers.
 pub trait CryptoNum {
+    /// Generate a new value of the given type.
     fn zero() -> Self;
+    /// Test if the number is zero.
     fn is_zero(&self) -> bool;
+    /// Test if the number is even.
     fn is_even(&self) -> bool;
+    /// Test if the number is odd.
     fn is_odd(&self) -> bool;
+    /// Mask off the high parts of the number. In particular, it
+    /// zeros the bits above (len * 64).
     fn mask(&mut self, len: usize);
 }
 

src/unsigned/codec.rs

@@ -1,7 +1,9 @@
+/// Conversion from bytes into the numeric type.
 pub trait Decoder {
     fn from_bytes(x: &[u8]) -> Self;
 }
 
+/// Conversion from the numeric types into a byte buffer.
 pub trait Encoder {
     fn to_bytes(&self) -> Vec<u8>;
 }

src/unsigned/div.rs

@@ -1,6 +1,9 @@
+/// Concurrent div/mod operations for a number, so that you don't
+/// have to do them separately.
 pub trait DivMod
  where Self: Sized
 {
+    /// Compute the quotient and remainder of a and b.
     fn divmod(&self, rhs: &Self) -> (Self, Self);
 }
 

src/unsigned/mod.rs

@@ -1,3 +1,18 @@
+//! This module includes a large number of unsigned integer types for very
+//! large integers, designed to try to match good performance with a high
+//! assurance threshold.
+//! 
+//! The types provided in this module, and the functions available for each
+//! of those types, is derived from standard bit widths for RSA, DSA, and
+//! Elliptic Curve encryption schemes. If this library does not include a
+//! function you would like for another cryptographic scheme, please reach
+//! out to the authors; in many cases, the relevant code can be automatically
+//! generated.
+//! 
+//! For performance reasons, we also include support for Barrett reduction,
+//! which should improve the speed of modular reduction of large numbers for
+//! those cases in which you will be frequently performing modulo operations
+//! using the same modulus.
 #[macro_use]
 mod add;
 #[macro_use]

src/unsigned/modexp.rs

@@ -1,4 +1,8 @@
+/// Modular exponentiation for a value.
 pub trait ModExp<T> {
+    /// Modular exponentiation using the given modulus type. If it's possible,
+    /// we suggest using Barrett values, which are much faster than doing
+    /// modulo with the number types.
     fn modexp(&self, e: &Self, m: &T) -> Self;
 }
 

src/unsigned/modmul.rs

@@ -1,4 +1,8 @@
+/// Modular multiplication of the type.
 pub trait ModMul<T> {
+    /// Modular multiplication using the given modulus type. If it's possible,
+    /// we suggest using Barrett values, which are much faster than doing
+    /// modulo with the number types.
     fn modmul(&self, x: &Self, m: &T) -> Self;
 }
 

src/unsigned/modsq.rs

@@ -1,4 +1,8 @@
+/// Modular squaring
 pub trait ModSquare<T> {
+    /// Modular squaring using the given modulus type. If it's possible,
+    /// we suggest using Barrett values, which are much faster than doing
+    /// modulo with the number types.
     fn modsq(&self, m: &T) -> Self;
 }
 

src/unsigned/square.rs

@@ -1,3 +1,4 @@
+/// Squaring of large numbers.
 pub trait Square<Output> {
     fn square(&self) -> Output;
 }