Test docs in CI (#539)

.github/workflows/ci.yaml

@@ -38,6 +38,16 @@ jobs:
           toolchain: nightly-2024-01-04
       - uses: Swatinem/rust-cache@v2
       - run: scripts/clippy.sh
+
+  doc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: nightly-2024-01-04
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo +nightly-2024-01-04 doc
 
   run-avx-tests:
     runs-on: avx

src/commitment_scheme/blake2s_ref.rs

@@ -1,5 +1,5 @@
 //! An AVX512 implementation of the BLAKE2s compression function.
-//! Based on https://github.com/oconnor663/blake2_simd/blob/master/blake2s/src/avx2.rs .
+//! Based on <https://github.com/oconnor663/blake2_simd/blob/master/blake2s/src/avx2.rs>.
 
 pub const IV: [u32; 8] = [
     0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A, 0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19,

src/commitment_scheme/mixed_degree_merkle_tree.rs

@@ -334,7 +334,7 @@ where
 }
 
 /// Translates queries of the form <column, entry_index> to the form <layer, node_index>
-/// Input queries are per column, i.e queries[0] is a vector of queries for the first column that
+/// Input queries are per column, i.e `queries[0]` is a vector of queries for the first column that
 /// was inserted to the tree's input in that layer.
 pub fn queried_nodes_in_layer<'a>(
     queries: impl Iterator<Item = &'a Vec<usize>>,

src/commitment_scheme/utils.rs

@@ -196,7 +196,7 @@ pub fn inject_hash_in_pairs<'a: 'b, 'b, H: Hasher>(
 
 /// Injects Field element values into existing hash inputs.
 ///
-/// For Large [MerkleTree] constructions, holding reference-arrays for every node
+/// For Large Merkle tree constructions, holding reference-arrays for every node
 /// in a layer hinders performance greatly. Hence, the input is traversed in small chunks,
 /// and the refrences are discarded upon use.
 ///

src/core/backend/avx512/blake2s_avx.rs

@@ -1,5 +1,5 @@
 //! An AVX512 implementation of the BLAKE2s compression function.
-//! Based on https://github.com/oconnor663/blake2_simd/blob/master/blake2s/src/avx2.rs .
+//! Based on <https://github.com/oconnor663/blake2_simd/blob/master/blake2s/src/avx2.rs>.
 
 use std::arch::x86_64::{
     __m512i, _mm512_add_epi32, _mm512_or_si512, _mm512_permutex2var_epi32, _mm512_set1_epi32,

src/core/backend/avx512/m31.rs

@@ -100,7 +100,7 @@ impl Display for PackedBaseField {
 impl Add for PackedBaseField {
     type Output = Self;
 
-    /// Adds two packed M31 elements, and reduces the result to the range [0,P].
+    /// Adds two packed M31 elements, and reduces the result to the range `[0,P]`.
     /// Each value is assumed to be in unreduced form, [0, P] including P.
     #[inline(always)]
     fn add(self, rhs: Self) -> Self::Output {
@@ -208,7 +208,7 @@ impl Neg for PackedBaseField {
     }
 }
 
-/// Subtracts two packed M31 elements, and reduces the result to the range [0,P].
+/// Subtracts two packed M31 elements, and reduces the result to the range `[0,P]`.
 /// Each value is assumed to be in unreduced form, [0, P] including P.
 impl Sub for PackedBaseField {
     type Output = Self;

src/core/commitment_scheme/utils.rs

@@ -24,7 +24,7 @@ impl<T> TreeVec<T> {
     }
 }
 
-/// Converts &TreeVec<T> to TreeVec<&T>.
+/// Converts `&TreeVec<T>` to `TreeVec<&T>`.
 impl<'a, T> From<&'a TreeVec<T>> for TreeVec<&'a T> {
     fn from(val: &'a TreeVec<T>) -> Self {
         val.as_ref()
@@ -59,9 +59,9 @@ impl<T> TreeVec<ColumnVec<T>> {
                 .collect(),
         )
     }
-    /// Zips two [TreeVec<ColumVec<T>>] with the same structure (number of columns in each tree).
-    /// The resulting [TreeVec<ColumVec<T>>] has the same structure, with each value being a tuple
-    /// of the corresponding values from the input [TreeVec<ColumVec<T>>].
+    /// Zips two [`TreeVec<ColumVec<T>>`] with the same structure (number of columns in each tree).
+    /// The resulting [`TreeVec<ColumVec<T>>`] has the same structure, with each value being a tuple
+    /// of the corresponding values from the input [`TreeVec<ColumVec<T>>`].
     pub fn zip_cols<U>(
         self,
         other: impl Into<TreeVec<ColumnVec<U>>>,
@@ -76,7 +76,8 @@ impl<T> TreeVec<ColumnVec<T>> {
     pub fn as_cols_ref(&self) -> TreeVec<ColumnVec<&T>> {
         TreeVec(self.iter().map(|column| column.iter().collect()).collect())
     }
-    /// Flattens the [TreeVec<ColumVec<T>>] into a single [ColumnVec] with all the columns combined.
+    /// Flattens the [`TreeVec<ColumVec<T>>`] into a single [`ColumnVec`] with all the columns
+    /// combined.
     pub fn flatten(self) -> ColumnVec<T> {
         self.0.into_iter().flatten().collect()
     }
@@ -89,14 +90,14 @@ impl<'a, T> From<&'a TreeVec<ColumnVec<T>>> for TreeVec<ColumnVec<&'a T>> {
 }
 
 impl<T> TreeVec<ColumnVec<Vec<T>>> {
-    /// Flattens a [TreeVec<ColumVec<T>>] of [Vec]s into a single [Vec] with all the elements
+    /// Flattens a [`TreeVec<ColumVec<T>>`] of [Vec]s into a single [Vec] with all the elements
     /// combined.
     pub fn flatten_cols(self) -> Vec<T> {
         self.0.into_iter().flatten().flatten().collect()
     }
 
     // TODO(spapini): Remove after accumulating oods quotients by size.
-    /// Flattens a [TreeVec<ColumVec<T>>] of [Vec]s into a single [Vec] with all the elements
+    /// Flattens a [`TreeVec<ColumVec<T>>`] of [Vec]s into a single [Vec] with all the elements
     /// combined, in reverse order.
     pub fn flatten_cols_rev(self) -> Vec<T> {
         self.0.into_iter().flatten().flatten().rev().collect()

src/core/fri.rs

@@ -89,14 +89,17 @@ pub trait FriOps: FieldOps<SecureField> + Sized {
     /// Folds and accumulates a degree `d` circle polynomial into a degree `d/2` univariate
     /// polynomial.
     ///
-    /// Let `src` be the evaluation of a circle polynomial `f` on a [CircleDomain] `E`. This
-    /// function computes evaluations of `f' = f0 + alpha * f1` on the x-coordinates of `E` such
-    /// that `2f(p) = f0(px) + py * f1(px)`. The evaluations of `f'` are accumulated into `dst`
-    /// by the formula `dst = dst * alpha^2 + f'`.
+    /// Let `src` be the evaluation of a circle polynomial `f` on a
+    /// [`CircleDomain`] `E`. This function computes evaluations of `f' = f0
+    /// + alpha * f1` on the x-coordinates of `E` such that `2f(p) = f0(px) + py * f1(px)`. The
+    /// evaluations of `f'` are accumulated into `dst` by the formula `dst = dst * alpha^2 +
+    /// f'`.
     ///
     /// # Panics
     ///
     /// Panics if `src` is not double the length of `dst`.
+    ///
+    /// [`CircleDomain`]: super::poly::circle::CircleDomain
     // TODO(andrew): Make folding factor generic.
     // TODO(andrew): Fold directly into FRI layer to prevent allocation.
     fn fold_circle_into_line<F: Field>(
@@ -127,7 +130,7 @@ impl<B: FriOps, H: Hasher<NativeType = u8>> FriProver<B, H> {
     /// Combining evaluations on different sized domains into an evaluation of a single polynomial
     /// on a single domain for the purpose of commitment is inefficient. Instead, commit to multiple
     /// polynomials so combining of evaluations can be taken care of efficiently at the appropriate
-    /// FRI layer. All evaluations must be taken over canonic [CircleDomain]s.
+    /// FRI layer. All evaluations must be taken over canonic [`CircleDomain`]s.
     ///
     /// # Panics
     ///
@@ -136,6 +139,8 @@ impl<B: FriOps, H: Hasher<NativeType = u8>> FriProver<B, H> {
     /// * An evaluation is not from a sufficiently low degree circle polynomial.
     /// * An evaluation's domain is smaller than the last layer.
     /// * An evaluation's domain is not a canonic circle domain.
+    ///
+    /// [`CircleDomain`]: super::poly::circle::CircleDomain
     // TODO(andrew): Add docs for all evaluations needing to be from canonic domains.
     pub fn commit<F>(
         channel: &mut impl Channel<Digest = H::Hash>,
@@ -632,7 +637,7 @@ pub const FOLD_STEP: u32 = 1;
 /// Number of folds when folding a circle polynomial to univariate polynomial.
 pub const CIRCLE_TO_LINE_FOLD_STEP: u32 = 1;
 
-/// Stores a subset of evaluations in a [FriLayer] with their corresponding merkle decommitments.
+/// Stores a subset of evaluations in a fri layer with their corresponding merkle decommitments.
 ///
 /// The subset corresponds to the set of evaluations needed by a FRI verifier.
 #[derive(Debug)]

src/core/poly/circle/domain.rs

@@ -72,7 +72,8 @@ impl CircleDomain {
     /// Returns true if the domain is canonic.
     ///
     /// Canonic domains are domains with elements that are the entire set of points defined by
-    /// `G_2n + <G_n>` where `G_n` and `G_2n` are obtained by repeatedly doubling [M31_CIRCLE_GEN].
+    /// `G_2n + <G_n>` where `G_n` and `G_2n` are obtained by repeatedly doubling
+    /// [crate::core::circle::M31_CIRCLE_GEN].
     pub fn is_canonic(&self) -> bool {
         self.half_coset.initial_index * 4 == self.half_coset.step_size
     }

src/core/poly/twiddles.rs

@@ -3,7 +3,7 @@ use crate::core::circle::Coset;
 
 /// Precomputed twiddles for a specific coset tower.
 /// A coset tower is every repeated doubling of a `root_coset`.
-/// The largest [CircleDomain] that can be ffted using these twiddles is one with `root_coset` as
+/// The largest CircleDomain that can be ffted using these twiddles is one with `root_coset` as
 /// its `half_coset`.
 pub struct TwiddleTree<B: PolyOps> {
     pub root_coset: Coset,

src/hash_functions/poseidon.rs

@@ -12,7 +12,7 @@ const POSEIDON_CAPACITY: usize = 8; // in BaseField elements.
 const POSEIDON_POWER: usize = 5;
 
 /// Parameters for the Poseidon hash function.
-/// For more info, see https://eprint.iacr.org/2019/458.pdf
+/// For more info, see <https://eprint.iacr.org/2019/458.pdf>
 pub struct PoseidonParams {
     pub rate: usize,
     pub capacity: usize,