Update documentation for BLS12 fields (#1)

bls12_377/src/fields/fq.rs

@@ -38,6 +38,7 @@ impl FpParameters for FqParameters {
 
     const REPR_SHAVE_BITS: u32 = 7;
 
+    /// R = 85013442423176922659824578519796707547925331718418265885885478904210582549405549618995257669764901891699128663912
     #[rustfmt::skip]
     const R: BigInteger = BigInteger([
         202099033278250856u64,
@@ -60,7 +61,9 @@ impl FpParameters for FqParameters {
 
     const INV: u64 = 9586122913090633727u64;
 
-    // GENERATOR = -5
+    /// GENERATOR = -5
+    /// Encoded in Montgomery form, so the value here is
+    /// (-5 * R) % q = 92261639910053574722182574790803529333160366917737991650341130812388023949653897454961487930322210790384999596794
     #[rustfmt::skip]
     const GENERATOR: BigInteger = BigInteger([
         0xfc0b8000000002fa,
@@ -82,6 +85,7 @@ impl FpParameters for FqParameters {
     ]);
 
     // T and T_MINUS_ONE_DIV_TWO, where MODULUS - 1 = 2^S * T
+    // For T coprime to 2
 
     // T = (MODULUS - 1) // 2^S =
     // 3675842578061421676390135839012792950148785745837396071634149488243117337281387659330802195819009059

bls12_377/src/fields/fr.rs

@@ -34,6 +34,7 @@ impl FpParameters for FrParameters {
 
     const REPR_SHAVE_BITS: u32 = 3;
 
+    /// R = 6014086494747379908336260804527802945383293308637734276299549080986809532403
     #[rustfmt::skip]
     const R: BigInteger = BigInteger([
         9015221291577245683u64,
@@ -52,7 +53,9 @@ impl FpParameters for FrParameters {
 
     const INV: u64 = 725501752471715839u64;
 
-    // GENERATOR = 11
+    /// GENERATOR = 11
+    /// Encoded in Montgomery form, so the value is
+    /// (11 * R) % q = 7043719196222586021957094278335006679584931048936630243748405699433040183146
     #[rustfmt::skip]
     const GENERATOR: BigInteger = BigInteger([
         1855201571499933546u64,
@@ -72,6 +75,7 @@ impl FpParameters for FrParameters {
     ]);
 
     // T and T_MINUS_ONE_DIV_TWO, where r - 1 = 2^s * t
+    // For T coprime to 2
 
     /// t = (r - 1) / 2^s =
     /// 60001509534603559531609739528203892656505753216962260608619555

bls12_381/src/fields/fq.rs

@@ -42,6 +42,7 @@ impl FpParameters for FqParameters {
 
     const REPR_SHAVE_BITS: u32 = 3;
 
+    /// R = 3380320199399472671518931668520476396067793891014375699959770179129436917079669831430077592723774664465579537268733
     #[rustfmt::skip]
     const R: BigInteger = BigInteger([
         0x760900000002fffd,
@@ -64,7 +65,9 @@ impl FpParameters for FqParameters {
 
     const INV: u64 = 0x89f3fffcfffcfffd;
 
-    // GENERATOR = 2
+    /// GENERATOR = 2
+    /// Encoded in Montgomery form, so the value is
+    /// 2 * R % q = 2758230843577277949620073511305048635578704962089743514587482222134842183668501798417467556318533664893264801977679
     #[rustfmt::skip]
     const GENERATOR: BigInteger = BigInteger([
         0x321300000006554f,
@@ -85,8 +88,8 @@ impl FpParameters for FqParameters {
         0xd0088f51cbff34d,
     ]);
 
-    // T and T_MINUS_ONE_DIV_TWO, where MODULUS - 1 = 2^S * T
-
+    /// T and T_MINUS_ONE_DIV_TWO, where MODULUS - 1 = 2^S * T
+    /// For T coprime to 2
     #[rustfmt::skip]
     const T: BigInteger = BigInteger([
         0xdcff7fffffffd555,

bls12_381/src/fields/fr.rs

@@ -37,6 +37,7 @@ impl FpParameters for FrParameters {
 
     const REPR_SHAVE_BITS: u32 = 1;
 
+    /// R = 10920338887063814464675503992315976177888879664585288394250266608035967270910
     #[rustfmt::skip]
     const R: BigInteger = BigInteger([
         0x1fffffffe,
@@ -55,7 +56,9 @@ impl FpParameters for FrParameters {
 
     const INV: u64 = 0xfffffffeffffffff;
 
-    //
+    /// GENERATOR = 7
+    /// Encoded in Montgomery form, so the value here is
+    /// 7 * R % q = 24006497034320510773280787438025867407531605151569380937148207556313189711857
     #[rustfmt::skip]
     const GENERATOR: BigInteger = BigInteger([
         0xefffffff1,
@@ -73,6 +76,7 @@ impl FpParameters for FrParameters {
     ]);
 
     // T and T_MINUS_ONE_DIV_TWO, where MODULUS - 1 = 2^S * T
+    // For T coprime to 2
 
     // T = (MODULUS - 1) / 2^S =
     // 12208678567578594777604504606729831043093128246378069236549469339647