From dd8770d8c4d48fe61b5bf8686316504bd67d1c02 Mon Sep 17 00:00:00 2001 From: Shahar Papini <43779613+spapinistarkware@users.noreply.github.com> Date: Tue, 26 Mar 2024 09:32:02 +0200 Subject: [PATCH] Test docs in CI (#539) --- .github/workflows/ci.yaml | 10 ++++++++++ src/commitment_scheme/blake2s_ref.rs | 2 +- .../mixed_degree_merkle_tree.rs | 2 +- src/commitment_scheme/utils.rs | 2 +- src/core/backend/avx512/blake2s_avx.rs | 2 +- src/core/backend/avx512/m31.rs | 4 ++-- src/core/commitment_scheme/utils.rs | 15 ++++++++------- src/core/fri.rs | 17 +++++++++++------ src/core/poly/circle/domain.rs | 3 ++- src/core/poly/twiddles.rs | 2 +- src/hash_functions/poseidon.rs | 2 +- 11 files changed, 39 insertions(+), 22 deletions(-) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index e42b09f1f..322f1d2b2 100644 --- a/.github/workflows/ci.yaml +++ b/.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 diff --git a/src/commitment_scheme/blake2s_ref.rs b/src/commitment_scheme/blake2s_ref.rs index 414279723..ab32ea6d9 100644 --- a/src/commitment_scheme/blake2s_ref.rs +++ b/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 . pub const IV: [u32; 8] = [ 0x6A09E667, 0xBB67AE85, 0x3C6EF372, 0xA54FF53A, 0x510E527F, 0x9B05688C, 0x1F83D9AB, 0x5BE0CD19, diff --git a/src/commitment_scheme/mixed_degree_merkle_tree.rs b/src/commitment_scheme/mixed_degree_merkle_tree.rs index 47dc5a20f..4d0890687 100644 --- a/src/commitment_scheme/mixed_degree_merkle_tree.rs +++ b/src/commitment_scheme/mixed_degree_merkle_tree.rs @@ -334,7 +334,7 @@ where } /// Translates queries of the form to the form -/// 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>, diff --git a/src/commitment_scheme/utils.rs b/src/commitment_scheme/utils.rs index f5d913539..34420c297 100644 --- a/src/commitment_scheme/utils.rs +++ b/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. /// diff --git a/src/core/backend/avx512/blake2s_avx.rs b/src/core/backend/avx512/blake2s_avx.rs index a720d86bf..d79ef0579 100644 --- a/src/core/backend/avx512/blake2s_avx.rs +++ b/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 . use std::arch::x86_64::{ __m512i, _mm512_add_epi32, _mm512_or_si512, _mm512_permutex2var_epi32, _mm512_set1_epi32, diff --git a/src/core/backend/avx512/m31.rs b/src/core/backend/avx512/m31.rs index a1efc34d6..bff995147 100644 --- a/src/core/backend/avx512/m31.rs +++ b/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; diff --git a/src/core/commitment_scheme/utils.rs b/src/core/commitment_scheme/utils.rs index 11f6444e4..202def62a 100644 --- a/src/core/commitment_scheme/utils.rs +++ b/src/core/commitment_scheme/utils.rs @@ -24,7 +24,7 @@ impl TreeVec { } } -/// Converts &TreeVec to TreeVec<&T>. +/// Converts `&TreeVec` to `TreeVec<&T>`. impl<'a, T> From<&'a TreeVec> for TreeVec<&'a T> { fn from(val: &'a TreeVec) -> Self { val.as_ref() @@ -59,9 +59,9 @@ impl TreeVec> { .collect(), ) } - /// Zips two [TreeVec>] with the same structure (number of columns in each tree). - /// The resulting [TreeVec>] has the same structure, with each value being a tuple - /// of the corresponding values from the input [TreeVec>]. + /// Zips two [`TreeVec>`] with the same structure (number of columns in each tree). + /// The resulting [`TreeVec>`] has the same structure, with each value being a tuple + /// of the corresponding values from the input [`TreeVec>`]. pub fn zip_cols( self, other: impl Into>>, @@ -76,7 +76,8 @@ impl TreeVec> { pub fn as_cols_ref(&self) -> TreeVec> { TreeVec(self.iter().map(|column| column.iter().collect()).collect()) } - /// Flattens the [TreeVec>] into a single [ColumnVec] with all the columns combined. + /// Flattens the [`TreeVec>`] into a single [`ColumnVec`] with all the columns + /// combined. pub fn flatten(self) -> ColumnVec { self.0.into_iter().flatten().collect() } @@ -89,14 +90,14 @@ impl<'a, T> From<&'a TreeVec>> for TreeVec> { } impl TreeVec>> { - /// Flattens a [TreeVec>] of [Vec]s into a single [Vec] with all the elements + /// Flattens a [`TreeVec>`] of [Vec]s into a single [Vec] with all the elements /// combined. pub fn flatten_cols(self) -> Vec { self.0.into_iter().flatten().flatten().collect() } // TODO(spapini): Remove after accumulating oods quotients by size. - /// Flattens a [TreeVec>] of [Vec]s into a single [Vec] with all the elements + /// Flattens a [`TreeVec>`] of [Vec]s into a single [Vec] with all the elements /// combined, in reverse order. pub fn flatten_cols_rev(self) -> Vec { self.0.into_iter().flatten().flatten().rev().collect() diff --git a/src/core/fri.rs b/src/core/fri.rs index 52210749a..67fa072b5 100644 --- a/src/core/fri.rs +++ b/src/core/fri.rs @@ -89,14 +89,17 @@ pub trait FriOps: FieldOps + 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( @@ -127,7 +130,7 @@ impl> FriProver { /// 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> FriProver { /// * 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( channel: &mut impl Channel, @@ -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)] diff --git a/src/core/poly/circle/domain.rs b/src/core/poly/circle/domain.rs index d47141221..2cc221d3f 100644 --- a/src/core/poly/circle/domain.rs +++ b/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 + ` where `G_n` and `G_2n` are obtained by repeatedly doubling [M31_CIRCLE_GEN]. + /// `G_2n + ` 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 } diff --git a/src/core/poly/twiddles.rs b/src/core/poly/twiddles.rs index b5adf8e27..53ea476c6 100644 --- a/src/core/poly/twiddles.rs +++ b/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 { pub root_coset: Coset, diff --git a/src/hash_functions/poseidon.rs b/src/hash_functions/poseidon.rs index f0eb0a388..0ba236bac 100644 --- a/src/hash_functions/poseidon.rs +++ b/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 pub struct PoseidonParams { pub rate: usize, pub capacity: usize,