Add math rendering with KaTeX.

Cargo.toml

@@ -9,6 +9,9 @@ repository = "https://github.com/zkcrypto/bls12_381"
 version = "0.0.0"
 edition = "2018"
 
+[package.metadata.docs.rs]
+rustdoc-args = [ "--html-in-header", "katex-header.html" ]
+
 [dependencies.subtle]
 version = "2.1"
 default-features = false

katex-header.html

@@ -0,0 +1,15 @@
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.css" integrity="sha384-9eLZqc9ds8eNjO3TmqPeYcDj8n+Qfa4nuSiGYa6DjLNcv9BtN69ZIulL9+8CqC9Y" crossorigin="anonymous">
+<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.js"                  integrity="sha384-K3vbOmF2BtaVai+Qk37uypf7VrgBubhQreNQe9aGsz9lB63dIFiQVlJbr92dw2Lx" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/contrib/auto-render.min.js"    integrity="sha384-kmZOZB5ObwgQnS/DuDg6TScgOiWWBiVt0plIRkZCmE6rDZGrEOQeHM5PcHi+nyqe" crossorigin="anonymous"></script>
+<script>
+    document.addEventListener("DOMContentLoaded", function() {
+        renderMathInElement(document.body, {
+            delimiters: [
+                {left: "$$", right: "$$", display: true},
+                {left: "\\(", right: "\\)", display: false},
+                {left: "$", right: "$", display: false},
+                {left: "\\[", right: "\\]", display: true}
+            ]
+        });
+    });
+</script>

src/g1.rs

@@ -1,13 +1,13 @@
-//! This module provides an implementation of the G1 group of BLS12-381.
+//! This module provides an implementation of the $\mathbb{G}_1$ group of BLS12-381.
 
 use crate::fp::Fp;
 use subtle::Choice;
 
-/// This is an element of G1 represented in the affine (x, y) coordinate space. It
+/// This is an element of $\mathbb{G}_1$ represented in the affine coordinate space.
-/// is ideal to keep elements in this representation to reduce memory usage and
+/// It is ideal to keep elements in this representation to reduce memory usage and
 /// improve performance through the use of mixed curve model arithmetic.
 ///
-/// Values of `G1Affine` are guaranteed to be in the q-order subgroup unless an
+/// Values of `G1Affine` are guaranteed to be in the $q$-order subgroup unless an
 /// "unchecked" API was misused.
 #[derive(Copy, Clone, Debug)]
 pub struct G1Affine {
@@ -16,7 +16,7 @@ pub struct G1Affine {
     infinity: Choice,
 }
 
-/// This is an element of G1 represented in the projective (X, Y, Z) coordinate space.
+/// This is an element of $\mathbb{G}_1$ represented in the projective coordinate space.
 #[derive(Copy, Clone, Debug)]
 pub struct G1Projective {
     x: Fp,

src/g2.rs

@@ -1,13 +1,13 @@
-//! This module provides an implementation of the G2 group of BLS12-381.
+//! This module provides an implementation of the $\mathbb{G}_2$ group of BLS12-381.
 
 use crate::fp2::Fp2;
 use subtle::Choice;
 
-/// This is an element of G2 represented in the affine (x, y) coordinate space. It
+/// This is an element of $\mathbb{G}_2$ represented in the affine coordinate space.
-/// is ideal to keep elements in this representation to reduce memory usage and
+/// It is ideal to keep elements in this representation to reduce memory usage and
 /// improve performance through the use of mixed curve model arithmetic.
 ///
-/// Values of `G2Affine` are guaranteed to be in the q-order subgroup unless an
+/// Values of `G2Affine` are guaranteed to be in the $q$-order subgroup unless an
 /// "unchecked" API was misused.
 #[derive(Copy, Clone, Debug)]
 pub struct G2Affine {
@@ -16,7 +16,7 @@ pub struct G2Affine {
     infinity: Choice,
 }
 
-/// This is an element of G2 represented in the projective (X, Y, Z) coordinate space.
+/// This is an element of $\mathbb{G}_2$ represented in the projective coordinate space.
 #[derive(Copy, Clone, Debug)]
 pub struct G2Projective {
     x: Fp2,

src/scalar.rs

@@ -1,4 +1,4 @@
-//! This module provides an implementation of the BLS12-381 scalar field `GF(q)`
+//! This module provides an implementation of the BLS12-381 scalar field $\mathbb{F}_q$
 //! where `q = 0x73eda753299d7d483339d80809a1d80553bda402fffe5bfeffffffff00000001`
 
 use core::fmt;
@@ -9,7 +9,8 @@ use subtle::{Choice, ConditionallySelectable, ConstantTimeEq, CtOption};
 
 use crate::util::{adc, mac, sbb};
 
-/// Represents a scalar of the BLS12-381 elliptic curve construction.
+/// Represents an element of the scalar field $\mathbb{F}_q$ of the BLS12-381 elliptic
+/// curve construction.
 // The internal representation of this type is four 64-bit unsigned
 // integers in little-endian order. `Scalar` values are always in
 // Montgomery form; i.e., Scalar(a) = aR mod q, with R = 2^256.