Improve documentation

src/cpa.rs

@@ -6,7 +6,7 @@ use rayon::{
 };
 use std::{iter::zip, ops::Add};
 
-/// Computes the [`Cpa`] of the given traces using [`CpaProcessor`].
+/// Compute the [`Cpa`] of the given traces using [`CpaProcessor`].
 ///
 /// # Panics
 /// - Panic if `leakages.shape()[0] != plaintexts.shape()[0]`
@@ -47,6 +47,9 @@ where
     .finalize()
 }
 
+/// Result of the CPA[^1] on some traces.
+///
+/// [^1]: <https://www.iacr.org/archive/ches2004/31560016/31560016.pdf>
 #[derive(Debug)]
 pub struct Cpa {
     /// Guess range upper excluded bound
@@ -56,16 +59,19 @@ pub struct Cpa {
 }
 
 impl Cpa {
+    /// Rank guesses.
     pub fn rank(&self) -> Array1<usize> {
         let rank = argsort_by(&self.max_corr().to_vec()[..], f32::total_cmp);
 
         Array1::from_vec(rank)
     }
 
+    /// Return the Pearson correlation coefficients.
     pub fn corr(&self) -> ArrayView2<f32> {
         self.corr.view()
     }
 
+    /// Return the guess with the highest Pearson correlation coefficient.
     pub fn best_guess(&self) -> usize {
         let max_corr = self.max_corr();
 
@@ -81,14 +87,17 @@ impl Cpa {
         best_guess
     }
 
+    /// Return the maximum Pearson correlation coefficient for each guess.
     pub fn max_corr(&self) -> Array1<f32> {
         max_per_row(self.corr.view())
     }
 }
 
 /// A processor that computes the [`Cpa`] of the given traces.
 ///
-/// It implements Algorithm 4 of https://eprint.iacr.org/2013/794.pdf
+/// It implements algorithm 4 from [^1].
+///
+/// [^1]: <https://eprint.iacr.org/2013/794.pdf>
 pub struct CpaProcessor<F>
 where
     F: Fn(usize, usize) -> usize,
@@ -108,7 +117,7 @@ where
     /// Sum of square of traces per key guess
     guess_sum_squares_leakages: Array1<usize>,
     /// Sum of traces per plaintext used
-    /// See 4.3 in https://eprint.iacr.org/2013/794.pdf
+    /// See 4.3 in <https://eprint.iacr.org/2013/794.pdf>
     plaintext_sum_leakages: Array2<usize>,
     /// Leakage model
     leakage_func: F,
@@ -165,7 +174,7 @@ where
         self.num_traces += 1;
     }
 
-    /// Finalizes the calculation after feeding the overall traces.
+    /// Finalize the calculation after feeding the overall traces.
     pub fn finalize(&self) -> Cpa {
         let mut modeled_leakages = Array1::zeros(self.guess_range);
 

src/cpa_normal.rs

@@ -4,7 +4,7 @@ use std::{iter::zip, ops::Add};
 
 use crate::cpa::Cpa;
 
-/// Computes the [`Cpa`] of the given traces using [`CpaProcessor`].
+/// Compute the [`Cpa`] of the given traces using [`CpaProcessor`].
 ///
 /// # Panics
 /// - Panic if `leakages.shape()[0] != plaintexts.shape()[0]`
@@ -42,6 +42,9 @@ where
     .finalize()
 }
 
+/// A processor that computes the [`Cpa`] of the given traces.
+///
+/// [^1]: <https://www.iacr.org/archive/ches2004/31560016/31560016.pdf>
 pub struct CpaProcessor<F>
 where
     F: Fn(ArrayView1<usize>, usize) -> usize,
@@ -68,9 +71,6 @@ where
     num_traces: usize,
 }
 
-/* This class implements the CPA algorithm shown in:
-https://www.iacr.org/archive/ches2004/31560016/31560016.pdf */
-
 impl<F> CpaProcessor<F>
 where
     F: Fn(ArrayView1<usize>, usize) -> usize,
@@ -144,7 +144,7 @@ where
         }
     }
 
-    /// Finalizes the calculation after feeding the overall traces.
+    /// Finalize the calculation after feeding the overall traces.
     pub fn finalize(&self) -> Cpa {
         let cov_n = self.cov.clone() / self.num_traces as f32;
         let avg_keys = self.guess_sum_leakages.clone() / self.num_traces as f32;

src/dpa.rs

@@ -4,8 +4,10 @@ use std::{iter::zip, marker::PhantomData, ops::Add};
 
 use crate::util::{argsort_by, max_per_row};
 
+/// Compute the [`Dpa`] of the given traces using [`DpaProcessor`].
+///
 /// # Panics
-/// Panics if `chunk_size` is not strictly positive.
+/// Panic if `chunk_size` is not strictly positive.
 pub fn dpa<M, T, F>(
     leakages: ArrayView2<T>,
     metadata: ArrayView1<M>,
@@ -40,6 +42,9 @@ where
     .finalize()
 }
 
+/// Result of the DPA[^1] on some traces.
+///
+/// [^1]: <https://paulkocher.com/doc/DifferentialPowerAnalysis.pdf>
 #[derive(Debug)]
 pub struct Dpa {
     /// Guess range upper excluded bound
@@ -48,16 +53,19 @@ pub struct Dpa {
 }
 
 impl Dpa {
+    /// Return the rank of guesses
     pub fn rank(&self) -> Array1<usize> {
         let rank = argsort_by(&self.max_differential_curves().to_vec()[..], f32::total_cmp);
 
         Array1::from_vec(rank)
     }
 
+    /// Return the differential curves
     pub fn differential_curves(&self) -> ArrayView2<f32> {
         self.differential_curves.view()
     }
 
+    /// Return the guess with the highest differential peak.
     pub fn best_guess(&self) -> usize {
         let max_corr = self.max_differential_curves();
 
@@ -73,16 +81,16 @@ impl Dpa {
         best_guess
     }
 
+    /// Return the maximum differential peak for each guess.
     pub fn max_differential_curves(&self) -> Array1<f32> {
         max_per_row(self.differential_curves.view())
     }
 }
 
 /// A processor that computes the [`Dpa`] of the given traces.
 ///
-/// It implements algorithm from:
-/// https://paulkocher.com/doc/DifferentialPowerAnalysis.pdf
-/// https://web.mit.edu/6.857/OldStuff/Fall03/ref/kocher-DPATechInfo.pdf
+/// [^1]: <https://paulkocher.com/doc/DifferentialPowerAnalysis.pdf>
+/// [^2]: <https://web.mit.edu/6.857/OldStuff/Fall03/ref/kocher-DPATechInfo.pdf>
 pub struct DpaProcessor<M, F>
 where
     F: Fn(M, usize) -> bool,