Add documentation warnings on FieldElement32 and FieldElement64.

src/field_32bit.rs

@@ -44,6 +44,19 @@ use utils::{load3, load4};
 /// The coefficients t[i] are allowed to grow between multiplications.
 ///
 /// XXX document by how much
+///
+/// # Warning
+///
+/// You almost certainly do not want to use `FieldElement32` directly.  Consider
+/// using `curve25519_dalek::field::FieldElement`, which will automatically
+/// select between `FieldElement32` and `FieldElement64` depending on whether
+/// curve25519-dalek was compiled with `--features="nightly"`.
+///
+/// This implementation, `FieldElement32`, is intended for platforms that can
+/// multiply 32-bit inputs to produce 64-bit outputs, and is not preferred for
+/// use on x86_64, since the 64-bit implementation is both much simpler and much
+/// faster.  However, the `FieldElement64` implementation requires Rust's
+/// `u128`, which is not yet stable.
 #[derive(Copy, Clone)]
 pub struct FieldElement32(pub [i32; 10]);
 

src/field_64bit.rs

@@ -38,6 +38,20 @@ pub type Limb = u64;
 /// In the 64-bit implementation, a `FieldElement` is represented in
 /// radix 2^51 as five `u64`s; the coefficients are allowed to grow up
 /// to 2^54 between reductions mod `p`.
+///
+/// # Warning
+///
+/// You almost certainly do not want to use `FieldElement64` directly.  Consider
+/// using `curve25519_dalek::field::FieldElement`, which will automatically
+/// select between `FieldElement32` and `FieldElement64` depending on whether
+/// curve25519-dalek was compiled with `--features="nightly"`.
+///
+/// This implementation, `FieldElement64`, is intended for x64_64 platforms,
+/// which have the `MUL` instructions taking 64-bit inputs and producing 128-bit
+/// outputs.  On other platforms, this implementation is not recommended.  On
+/// Haswell and newer, the BMI2 instruction set provides `MULX` and friends,
+/// which gives even better performance.  This implementation requires Rust's
+/// `u128`, which is not yet stable.
 #[derive(Copy, Clone)]
 pub struct FieldElement64(pub [u64; 5]);