Add some lightweight documentation.

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;
@@ -27,7 +30,9 @@ macro_rules! barrett_impl {
                // Done!
                $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;
 }