From 0e6fe6eda7089a720da1ab130e6df681ea313f45 Mon Sep 17 00:00:00 2001
From: PlexSheep <PlexSheep@protonmail.com>
Date: Mon, 8 May 2023 01:20:28 +0200
Subject: [PATCH] fancy module system

---
 src/{binary.rs => binary/mod.rs}              |  8 +++++
 src/lib.rs                                    | 18 ++++++++++--
 src/main.rs                                   | 29 +++++++++++++------
 src/math/mod.rs                               |  4 +++
 .../modexp.rs}                                | 10 ++++++-
 5 files changed, 57 insertions(+), 12 deletions(-)
 rename src/{binary.rs => binary/mod.rs} (56%)
 create mode 100644 src/math/mod.rs
 rename src/{modular_exponentiation.rs => math/modexp.rs} (91%)

diff --git a/src/binary.rs b/src/binary/mod.rs
similarity index 56%
rename from src/binary.rs
rename to src/binary/mod.rs
index 484896c..e7c378d 100644
--- a/src/binary.rs
+++ b/src/binary/mod.rs
@@ -1,4 +1,12 @@
 #![allow(dead_code)]
+/// binary functions
+///
+/// This module contains some functions that manipulate binary values.
+///
+/// Author:     Christoph J. Scherr <software@cscherr.de>
+/// License:    MIT
+/// Source:     <https://git.cscherr.de/PlexSheep/plexcryptool/>
+
 /**
  * Pythons bit operations are trash, so I made a rust lib for that.
  */
diff --git a/src/lib.rs b/src/lib.rs
index ec9ff39..f489ba7 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,7 +1,21 @@
+#![warn(missing_docs)]
+#![warn(clippy::missing_docs_in_private_items)]
+//! # various tools for use in cryptology contexts
+//!
+//! This is a mixed rust/python library that also offers an executable.
+//! The intended usage is the solving of tasks for cryptology and maybe math, in the context of a
+//! university degree. I wrote this for cryptology at DHBW Mannheim.
+//!
+//! ___
+//! Author:     Christoph J. Scherr <software@cscherr.de>
+//!
+//! License:    MIT
+//!
+//! Source:     <https://git.cscherr.de/PlexSheep/plexcryptool/>
 use pyo3::prelude::*;
 
 mod binary;
-mod modular_exponentiation;
+mod math;
 
 #[pymodule]
 fn register_binary_module(py: Python, parent_module: &PyModule) -> PyResult<()> {
@@ -15,7 +29,7 @@ fn register_binary_module(py: Python, parent_module: &PyModule) -> PyResult<()>
 #[pymodule]
 fn register_math_module(py: Python, parent_module: &PyModule) -> PyResult<()> {
     let math_module = PyModule::new(py, "math")?;
-    math_module.add_function(wrap_pyfunction!(modular_exponentiation::py_modular_exponentiation, math_module)?)?;
+    math_module.add_function(wrap_pyfunction!(math::modexp::py_modular_exponentiation, math_module)?)?;
     parent_module.add_submodule(math_module)?;
     Ok(())
 }
diff --git a/src/main.rs b/src/main.rs
index 4678d59..f3d58ef 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,10 +1,22 @@
+#![warn(missing_docs)]
+#![warn(clippy::missing_docs_in_private_items)]
+//!
+//! This is a mixed rust/python library that also offers an executable.
+//! The intended usage is the solving of tasks for cryptology and maybe math, in the context of a
+//! # various tools for use in cryptology contexts
+//! university degree. I wrote this for cryptology at DHBW Mannheim.
+//!
+//! ___
+//! Author:     Christoph J. Scherr <software@cscherr.de>
+//!
+//! License:    MIT
+//!
+//! Source:     <https://git.cscherr.de/PlexSheep/plexcryptool/>
 mod binary;
-mod modular_exponentiation;
+mod math;
 
 use std::{str::FromStr, fmt::Debug};
 
-use modular_exponentiation::modular_exponentiation;
-
 use clap::{Args, Parser, Subcommand};
 use num_bigint;
 /*************************************************************************************************/
@@ -74,6 +86,10 @@ struct RotateArgs {
 }
 
 /*************************************************************************************************/
+/// main function of plexcryptool.
+///
+/// This function is the entrypoint of the binary. It parses Commandline options and calls the
+/// internal functions with the corresponding values, then shows the results to the user.
 pub fn main() {
     let args = Cli::parse();
     match args.command {
@@ -83,7 +99,7 @@ pub fn main() {
                     let b = num_bigint::BigInt::from_str(&mod_exp_args.base.as_str()).expect("could not make bigint");
                     let e = num_bigint::BigInt::from_str(&mod_exp_args.exp.as_str()).expect("could not make bigint");
                     let f = num_bigint::BigInt::from_str(&mod_exp_args.field.as_str()).expect("could not make bigint");
-                    let result = modular_exponentiation(b.clone(), e, f, args.verbose);
+                    let result = math::modexp::modular_exponentiation(b.clone(), e, f, args.verbose);
                     if args.machine {
                         println!("{}", result)
                     }
@@ -113,10 +129,5 @@ pub fn main() {
             }
             
         }
-
-        // Fallback, this should ideally not execute
-        _ => {
-            eprintln!("Command not implemented.\n");
-        }
     }
 }
diff --git a/src/math/mod.rs b/src/math/mod.rs
new file mode 100644
index 0000000..d77d4bc
--- /dev/null
+++ b/src/math/mod.rs
@@ -0,0 +1,4 @@
+/// # math module
+///
+/// funcionality for math things. Contains tedious algorithms like binary exponentiation.
+pub mod modexp;
diff --git a/src/modular_exponentiation.rs b/src/math/modexp.rs
similarity index 91%
rename from src/modular_exponentiation.rs
rename to src/math/modexp.rs
index d9dbad9..4fe4dc5 100644
--- a/src/modular_exponentiation.rs
+++ b/src/math/modexp.rs
@@ -1,6 +1,14 @@
 #![allow(dead_code)]
+/// modular exponentiaton
+///
+/// Implements fast exponentiation with applied modulo. Usefull for calculations in a gallois
+/// field.
+///
+/// Author:     Christoph J. Scherr <software@cscherr.de>
+/// License:    MIT
+/// Source:     <https://git.cscherr.de/PlexSheep/plexcryptool/>
 
-use num_bigint::{BigInt, BigUint};
+use num_bigint::BigInt;
 use num_traits::ToPrimitive;
 use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;