Brief pass over documentation

Author: jnsiemer

src/error.rs

@@ -6,28 +6,30 @@
 // the terms of the Mozilla Public License Version 2.0 as published by the
 // Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
 
+//! Contains our central error enum for easy error propagation.
+//! 
 //! This module contains this crate's error enum. This enum can hold all sorts
 //! of errors occurring in this crate s.t. error propagation is simple for
 //! developers of this crate and all sorts of thrown errors and error types can
 //! be easily found and accessed by developers using this crate. Furthermore,
 //! the actual errors are wrapped s.t. all information about the error can be
 //! unwrapped again.
-//!
-//! **For developers:**
-//! - How to add an error to an `enum`? First of all, find a name
-//!   that is not too specific for your current case s.t. it could be used in other
-//!   contexts afterwards as well. Then, find the spot according to your chosen error
-//!   name in a alphanumerically sorted way in the list of supported errors in the doc
-//!   comment and inside the `enum` itself.
-//!   Afterwards, add the error to the list of implemented error
-//!   types in the doc comment of the `enum` with a short description when it is thrown.
-//!   Probably use this description for the doc comment above the implementation of
-//!   error in the `enum`. Then, add `#[error(<error msg>)]` to define the error message
-//!   output once your error is thrown. Below, write down `<error name>(<input>),` to
-//!   define the error with its name and possibly some inputs. The input can be of the
-//!   form [`String`], but also another error, whose conversion must be declared via
-//!   `#[from] OtherError`. It is best to use the existing structure as a guide. For any
-//!   further information, check out the here used [`thiserror`]-crate.
+
+// **For developers:**
+// - How to add an error to an `enum`? First of all, find a name
+//   that is not too specific for your current case s.t. it could be used in other
+//   contexts afterwards as well. Then, find the spot according to your chosen error
+//   name in a alphanumerically sorted way in the list of supported errors in the doc
+//   comment and inside the `enum` itself.
+//   Afterwards, add the error to the list of implemented error
+//   types in the doc comment of the `enum` with a short description when it is thrown.
+//   Probably use this description for the doc comment above the implementation of
+//   error in the `enum`. Then, add `#[error(<error msg>)]` to define the error message
+//   output once your error is thrown. Below, write down `<error name>(<input>),` to
+//   define the error with its name and possibly some inputs. The input can be of the
+//   form [`String`], but also another error, whose conversion must be declared via
+//   `#[from] OtherError`. It is best to use the existing structure as a guide. For any
+//   further information, check out the here used [`thiserror`]-crate.
 
 use std::ffi::NulError;
 use thiserror::Error;

src/integer.rs

@@ -6,6 +6,8 @@
 // the terms of the Mozilla Public License Version 2.0 as published by the
 // Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
 
+//! Integer-based types with arbitrary length based on [`Z`].
+//! 
 //! This module contains the type [`Z`] for integers with arbitrary length and
 //! constructions over it.
 //! Each struct provides examples regarding usage.

src/integer_mod_q.rs

@@ -6,6 +6,8 @@
 // the terms of the Mozilla Public License Version 2.0 as published by the
 // Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
 
+//! Types for residue classes over integers with arbitrary length based on [`Zq`].
+//! 
 //! This module contains the type [`Zq`] for integers with arbitrary length
 //! modulus `q` and constructions over it.
 //! Each struct provides examples regarding usage.
@@ -14,10 +16,6 @@
 //! e.g. the standard rust integers.
 //! The [`Modulus`] is constructed as an explicit struct and can be shared across several
 //! [`Zq`], [`MatZq`] and [`PolyOverZq`] instances with efficient memory usage.
-//!
-//! - \[1\] John D. Dixon.
-//!   "Exact Solution of Linear Equations Using P-Adic Expansions"
-//!   <https://link.springer.com/article/10.1007/BF01459082>
 
 mod mat_ntt_polynomial_ring_zq;
 mod mat_polynomial_ring_zq;

src/integer_mod_q/mat_polynomial_ring_zq/reduce.rs

@@ -8,11 +8,11 @@
 
 //! Implementations to reduce a [`MatPolynomialRingZq`] with the
 //! [`ModulusPolynomialRingZq`](crate::integer_mod_q::ModulusPolynomialRingZq).
-//!
-//! **For Developers** note: The [`ModulusPolynomialRingZq`](crate::integer_mod_q::ModulusPolynomialRingZq)
-//! is not applied automatically, and has to be called in the functions individually.
-//! Additionally the comparisons assume that the entries are reduced,
-//! hence no reduction is performed in the check.
+
+// **For Developers** note: The [`ModulusPolynomialRingZq`](crate::integer_mod_q::ModulusPolynomialRingZq)
+// is not applied automatically, and has to be called in the functions individually.
+// Additionally the comparisons assume that the entries are reduced,
+// hence no reduction is performed in the check.
 
 use super::MatPolynomialRingZq;
 use crate::traits::MatrixDimensions;

src/integer_mod_q/mat_zq.rs

@@ -8,10 +8,10 @@
 
 //! [`MatZq`] is a type of matrix with integer entries of arbitrary length modulo `q`.
 //! This implementation uses the [FLINT](https://flintlib.org/) library.
-//!
-//! For **DEVELOPERS**: Many functions assume that the [`MatZq`] instances are reduced.
-//! To avoid unnecessary checks and reductions, always return canonical/reduced
-//! values. The end-user should be unable to obtain a non-reduced value.
+
+// For **DEVELOPERS**: Many functions assume that the [`MatZq`] instances are reduced.
+// To avoid unnecessary checks and reductions, always return canonical/reduced
+// values. The end-user should be unable to obtain a non-reduced value.
 
 use crate::{integer_mod_q::Modulus, utils::parse::partial_string};
 use flint_sys::fmpz_mod_mat::fmpz_mod_mat_struct;

src/integer_mod_q/mat_zq/solve.rs

@@ -19,7 +19,7 @@ impl MatZq {
     /// The function uses Gaussian elimination together with Factor refinement
     /// to split the modulus and the Chinese remainder theorem and Hensel lifting
     /// to combine solutions under the split modulus.
-    /// For Hensel lifting we use the method from [\[1\]](<index.html#:~:text=[1]>).
+    /// For Hensel lifting we use the method from [\[1\]].
     ///
     /// Note that this function does not compute a solution whenever there is one.
     /// If the matrix has not full rank under a modulus that divides the given one,
@@ -48,6 +48,11 @@ impl MatZq {
     /// - if the the number of rows of the matrix and the syndrome are different.
     /// - if the syndrome is not a column vector.
     /// - if the moduli mismatch.
+    /// 
+    /// # Reference
+    /// - \[1\] John D. Dixon.
+    ///   "Exact Solution of Linear Equations Using P-Adic Expansions"
+    ///   <https://link.springer.com/article/10.1007/BF01459082>
     pub fn solve_gaussian_elimination(&self, y: &MatZq) -> Option<MatZq> {
         assert!(y.is_column_vector(), "The syndrome is not a column vector.");
         assert_eq!(
@@ -217,7 +222,7 @@ impl MatZq {
     }
 
     /// Computes a solution for a system of linear equations under a modulus
-    /// of the form `z^a` with the help of [\[1\]](<index.html#:~:text=[1]>).
+    /// of the form `z^a` with the help of [\[1\]].
     /// It solves `Ax = y` for `x` with `A` being a [`MatZq`] value.
     /// If no solution is found, `None` is returned.
     ///
@@ -339,7 +344,7 @@ impl MatZq {
             };
         }
 
-        // Use the method from [\[1\]](<index.html#:~:text=[1]>)
+        // Use the method from [\[1\]]
         // to compute a solution for the original system.
         let mut b_i = y.clone();
         let mut x_i = &matrix_base_inv * &b_i;

src/integer_mod_q/poly_over_zq.rs

@@ -9,10 +9,10 @@
 //! [`PolyOverZq`] is a type of polynomial with arbitrarily many coefficients of type
 //! [`Zq`](crate::integer_mod_q::Zq).
 //! This implementation uses the [FLINT](https://flintlib.org/) library.
-//!
-//! For **DEVELOPERS**: Many functions assume that the [`PolyOverZq`] instances are reduced.
-//! To avoid unnecessary checks and reductions, always return canonical/reduced
-//! values. The end-user should be unable to obtain a non-reduced value.
+
+// For **DEVELOPERS**: Many functions assume that the [`PolyOverZq`] instances are reduced.
+// To avoid unnecessary checks and reductions, always return canonical/reduced
+// values. The end-user should be unable to obtain a non-reduced value.
 
 use super::modulus::Modulus;
 use flint_sys::fmpz_mod_poly::fmpz_mod_poly_struct;

src/integer_mod_q/polynomial_ring_zq.rs

@@ -9,12 +9,12 @@
 //! [`PolynomialRingZq`] is a type of ring over PolyOverZq/f(X).
 //! Where f(X) is a [`PolyOverZq`](crate::integer_mod_q::PolyOverZq).
 //! This implementation uses the [FLINT](https://flintlib.org/) library.
-//!
-//! For **DEVELOPERS**: Many functions assume that the [`PolynomialRingZq`] instances are reduced.
-//! To avoid unnecessary checks and reductions, always return canonical/reduced
-//! values. The end-user should be unable to obtain a non-reduced value.
-//! Therefore, the DEVELOPER has to call the [`PolynomialRingZq::reduce`], whenever
-//! a computation may exceed the modulus, because it is not reduced automatically
+
+// For **DEVELOPERS**: Many functions assume that the [`PolynomialRingZq`] instances are reduced.
+// To avoid unnecessary checks and reductions, always return canonical/reduced
+// values. The end-user should be unable to obtain a non-reduced value.
+// Therefore, the DEVELOPER has to call the [`PolynomialRingZq::reduce`], whenever
+// a computation may exceed the modulus, because it is not reduced automatically
 
 use super::ModulusPolynomialRingZq;
 use crate::integer::PolyOverZ;

src/integer_mod_q/polynomial_ring_zq/reduce.rs

@@ -8,11 +8,11 @@
 
 //! Implementations to reduce a [`PolynomialRingZq`] with the
 //! [`ModulusPolynomialRingZq`](crate::integer_mod_q::ModulusPolynomialRingZq).
-//!
-//! **For Developers** note: The [`ModulusPolynomialRingZq`](crate::integer_mod_q::ModulusPolynomialRingZq)
-//! is not applied automatically, and has to be called in the functions individually.
-//! Additionally the comparisons assume that the entries are reduced,
-//! hence no reduction is performed in the check.
+
+// **For Developers** note: The [`ModulusPolynomialRingZq`](crate::integer_mod_q::ModulusPolynomialRingZq)
+// is not applied automatically, and has to be called in the functions individually.
+// Additionally the comparisons assume that the entries are reduced,
+// hence no reduction is performed in the check.
 
 use super::PolynomialRingZq;
 use flint_sys::fq::fq_reduce;

src/integer_mod_q/z_q.rs

@@ -13,10 +13,10 @@
 //! FLINT uses a `fmpz_mod_ctx_struct` to store functions and data used for
 //! optimizing modulo operations.
 //! This struct is wrapped in [`Modulus`] for easy use.
-//!
-//! For **DEVELOPERS**: Many functions assume that the [`Zq`] instances are reduced.
-//! To avoid unnecessary checks and reductions, always return canonical/reduced
-//! values. The end-user should be unable to obtain a non-reduced value.
+
+// For **DEVELOPERS**: Many functions assume that the [`Zq`] instances are reduced.
+// To avoid unnecessary checks and reductions, always return canonical/reduced
+// values. The end-user should be unable to obtain a non-reduced value.
 
 use super::Modulus;
 use crate::integer::Z;