CentralizedTelescope: Adding doc

src/centralized_telescope/params.rs

@@ -1,4 +1,4 @@
-//! Centralized Telescope's Params structure comprising the internal parameters
+//! Centralized Telescope's `Params` structure comprising the internal parameters
 
 use std::f64::consts::LOG2_E;
 
@@ -18,7 +18,25 @@ pub struct Params {
 }
 
 impl Params {
-    /// Setup algorithm taking a Params as input and returning Params parameters (u,d,q)
+    /// Returns a `Params` structure from user parameters
+    ///
+    /// # Arguments
+    ///
+    /// * `soundness_param` - the protocol soundness parameter, typically set at 128
+    /// * `completeness_param` - the protocol completeness parameter, typically set at 128
+    /// * `set_size` - the size of the prover set to lower bound
+    /// * `lower_bound` - the lower bound to prove
+    ///
+    /// # Returns
+    ///
+    /// A `Params` structure
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use alba::centralized_telescope::params::Params;
+    /// let params = Params::new(128.0, 128.0, 1_000, 750);
+    /// ```
     pub fn new(
         soundness_param: f64,
         completeness_param: f64,

src/centralized_telescope/proof.rs

@@ -1,4 +1,4 @@
-//! Centralized Telescope Proof structure
+//! Centralized Telescope's `Proof` structure
 
 #![doc = include_str!("../../docs/rustdoc/centralized_telescope/proof.md")]
 
@@ -23,17 +23,38 @@ pub struct Proof {
 
 impl Proof {
     /// Centralized Telescope's proving algorithm, based on a DFS algorithm.
-    /// Calls up to params.max_retries times the prove_index function and
+    /// Calls up to `params.max_retries` times the prove_index function and
     /// returns a `Proof` if a suitable candidate tuple is found.
+    ///
+    /// # Arguments
+    ///
+    /// * `set_size` - the size of the prover set to lower bound
+    /// * `params` - the internal parameters to generate a proof from
+    /// * `prover_set` - the dataset to generate a proof from
+    ///
+    /// # Returns
+    ///
+    /// A `Proof` structure
     pub(super) fn new(set_size: u64, params: &Params, prover_set: &[Element]) -> Option<Self> {
         // Run prove_index up to max_retries times
         (0..params.max_retries).find_map(|retry_counter| {
             Self::prove_index(set_size, params, prover_set, retry_counter).1
         })
     }
 
-    // Alba's verification algorithm, returns true if the proof is
-    /// successfully verified, following the DFS verification, false otherwise.
+    /// Centralized Telescope's verification algorithm, returns true if the
+    /// proof is successfully verified, following the DFS verification, false
+    /// otherwise.
+    ///
+    /// # Arguments
+    ///
+    /// * `self` - the proof to verify
+    /// * `set_size` - the size of the prover set to lower bound
+    /// * `params` - the internal parameters to generate a proof from
+    ///
+    /// # Returns
+    ///
+    /// A boolean, true if the proof verifies successfully otherwise false
     pub(super) fn verify(&self, set_size: u64, params: &Params) -> bool {
         if self.search_counter >= params.search_width
             || self.retry_counter >= params.max_retries
@@ -68,8 +89,8 @@ impl Proof {
     }
 
     /// Indexed proving algorithm, returns the total number of DFS calls done
-    /// to find a proof and Some(proof) if found within params.dfs_bound calls
-    /// of DFS, otherwise None
+    /// to find a proof and `Some(proof)` if found within `params.dfs_bound` calls
+    /// of DFS, otherwise `None`
     fn prove_index(
         set_size: u64,
         params: &Params,
@@ -118,7 +139,7 @@ impl Proof {
     /// Depth-First Search (DFS) algorithm which goes through all potential
     /// round candidates and returns the total number of recursive DFS calls
     /// done and, if not found under params.dfs_bound calls, None otherwise
-    /// Some(Proof), that is the first "round", i.e. the first proof candidate,
+    /// `Some(Proof)`, that is the first "round", i.e. the first proof candidate,
     /// Round{retry_counter, search_counter, x_1, ..., x_u)} such that:
     /// - ∀i ∈ [0, u-1], bin_hash(x_i+1) ∈ bins[round_hash(...round_hash(round_hash(v, t), x_1), ..., x_i)]
     /// - proof_hash(round_hash(... round_hash((round_hash(v, t), x_1), ..., x_u)) = true

src/centralized_telescope/round.rs

@@ -1,4 +1,4 @@
-//! ALBA's Round structure and associated functions
+//! Centralized Telescope's `Round` structure and associated functions
 
 #![doc = include_str!("../../docs/rustdoc/centralized_telescope/round.md")]
 

src/centralized_telescope/telescope.rs

@@ -1,3 +1,4 @@
+//! Customer facing Centralized Telescope structure
 use super::params::Params;
 use super::proof::Proof;
 use crate::utils::types::Element;
@@ -12,7 +13,25 @@ pub struct Telescope {
 }
 
 impl Telescope {
-    /// Initialize ALBA with `Params`.
+    /// Returns a `Telescope` structure from input parameters
+    ///
+    /// # Arguments
+    ///
+    /// * `soundness_param` - the protocol soundness parameter, typically set at 128
+    /// * `completeness_param` - the protocol completeness parameter, typically set at 128
+    /// * `set_size` - the size of the prover set to lower bound
+    /// * `lower_bound` - the lower bound to prove
+    ///
+    /// # Returns
+    ///
+    /// A `Telescope`` structure
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use alba::centralized_telescope::Telescope;
+    /// let telescope = Telescope::create(128.0, 128.0, 1_000, 750);
+    /// ```
     pub fn create(
         soundness_param: f64,
         completeness_param: f64,
@@ -23,23 +42,84 @@ impl Telescope {
         Self { set_size, params }
     }
 
-    /// Initialize ALBA with `set_size` and unchecked `Setup`.
-    /// Use with caution, in tests or with trusted parameters.
+    /// Use with caution. Returns a `Telescope` structure from input and
+    /// internal parameters without checking the consistency between parameters
+    ///
+    /// # Arguments
+    ///
+    /// * `set_size` - the size of the prover set to lower bound
+    /// * `params` - some centralized Telescope internal parameters
+    ///
+    /// # Returns
+    ///
+    /// A `Telescope` structure
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use alba::centralized_telescope::Telescope;
+    /// use alba::centralized_telescope::params::Params;
+    /// let params = Params {proof_size : 200, max_retries: 128, search_width: 10, valid_proof_probability: 0.001, dfs_bound: 40_000};
+    /// let telescope = Telescope::setup_unsafe(1_000, &params);
+    /// ```
     pub fn setup_unsafe(set_size: u64, params: &Params) -> Self {
         Self {
             set_size,
             params: *params,
         }
     }
 
-    /// Alba's proving algorithm, based on a depth-first search algorithm.
-    /// Returns either a `Proof` or `None` if no proof is found.
+    /// Generates a Centralized Telescope proof.
+    ///
+    /// # Arguments
+    ///
+    /// * `self` - the current `Telescope` structure
+    /// * `prover_set` - an array of elements to generate an Alba proof on
+    ///
+    /// # Returns
+    ///
+    /// A `Proof` if found, `None` otherwise
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use alba::centralized_telescope::Telescope;
+    /// let set_size = 200;
+    /// let telescope = Telescope::create(64.0, 64.0, set_size, 100);
+    /// let mut prover_set = Vec::new();
+    /// for i in 0..set_size {
+    ///     prover_set.push([(i % 256) as u8 ; 48]);
+    /// }
+    /// let proof = telescope.prove(&prover_set).unwrap();
+    /// ```
     pub fn prove(&self, prover_set: &[Element]) -> Option<Proof> {
         Proof::new(self.set_size, &self.params, prover_set)
     }
 
-    /// Alba's verification algorithm.
-    /// Returns true if and only if the proof is successfully verified.
+    /// Verifies a Centralized Telescope proof.
+    ///
+    /// # Arguments
+    ///
+    /// * `self` - the current `Telescope` structure
+    /// * `proof` - a centralized Telescope proof
+    ///
+    /// # Returns
+    ///
+    /// True if the verification is successful, false otherwise
+    ///
+    /// # Example
+    ///
+    /// ```
+    /// use alba::centralized_telescope::Telescope;
+    /// let set_size = 200;
+    /// let telescope = Telescope::create(64.0, 64.0, set_size, 100);
+    /// let mut prover_set = Vec::new();
+    /// for i in 0..set_size {
+    ///     prover_set.push([(i % 256) as u8 ; 48]);
+    /// }
+    /// let proof = telescope.prove(&prover_set).unwrap();
+    /// assert!(telescope.verify(&proof));
+    /// ```
     pub fn verify(&self, proof: &Proof) -> bool {
         proof.verify(self.set_size, &self.params)
     }