From c60aaa1aaeb0432bea218200b713a9319b83ad4f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20Rativel?=
 <remi.rativel@etudiant.univ-rennes1.fr>
Date: Tue, 9 May 2023 22:02:22 +0200
Subject: [PATCH] Documentation for the simulator

---
 src/simulator/interrupt.rs        | 22 +++++++++++++++++++++
 src/simulator/loader.rs           | 18 ++++++++++++++++-
 src/simulator/mem_cmp.rs          |  2 +-
 src/simulator/mmu.rs              |  4 ++--
 src/simulator/translationtable.rs | 32 +++++++++++++++++++++----------
 5 files changed, 64 insertions(+), 14 deletions(-)

diff --git a/src/simulator/interrupt.rs b/src/simulator/interrupt.rs
index c4be710..fd5ca7f 100644
--- a/src/simulator/interrupt.rs
+++ b/src/simulator/interrupt.rs
@@ -1,17 +1,38 @@
+//! # Interrupt
+//!
+//! This module contains an interrupt Handler.
+//! The methodes one_trick and idle aren't implemented for now
 
+/// # Interrupt
+///
+/// Interrupt Handler
 #[derive(PartialEq)]
 pub struct Interrupt {
+    /// Current Status
     level: InterruptStatus
 }
 
 impl Interrupt {
 
+    /// Interrupt constructor
+    ///
+    /// ### Return
+    /// Interrupt with status Off
     pub fn new() -> Self {
         Self {
             level: InterruptStatus::InterruptOff
         }
     }
 
+    /// Interrupt setter
+    /// Change the value of the Interrupt
+    ///
+    /// ### Parameters
+    /// - **self** the interupt handler
+    /// - **new_status** the new status value
+    ///
+    /// ### return
+    /// The previus status
     pub fn set_status(&mut self, new_status: InterruptStatus) -> InterruptStatus {
         let old = self.level;
         self.level = new_status;
@@ -25,6 +46,7 @@ impl Interrupt {
         todo!();
     }
 
+    /// Interupt getter
     pub fn get_status(&self) -> InterruptStatus {
         self.level
     }
diff --git a/src/simulator/loader.rs b/src/simulator/loader.rs
index 18f56fe..2aa8789 100644
--- a/src/simulator/loader.rs
+++ b/src/simulator/loader.rs
@@ -1,9 +1,25 @@
+//! # Loader
+//!
+//! This module contains a loader for file section.
+//! Following the common standard file format for executable files
+//! [ELF (Executable and Linkable Format)](https://en.wikipedia.org/wiki/Executable_and_Linkable_Forma)
+//!
+//! It's used to charge a programme into the machine from a binary file (.guac files)
+//!
+//!  Basic usage:
+//!
+//! ```
+//! let args = Args::parse();
+//! let mut machine = Machine::new(args.debug & 1 != 0, read_settings().unwrap());
+//! let (loader, ptr) = loader::Loader::new(args.executable.as_str(), &mut machine, 0).expect("An error occured while parsing the program");
+//! ```
+
 use crate::Machine;
 use std::fs;
 use std::io::Read;
 
 /// The elf header defines principes aspects of the binary files, it's place at the start of the file
-/// see <https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header> for more informations
+/// see [ELF file Header](https://en.wikipedia.org/wiki/Executable_and_Linkable_Format#File_header) for more informations
 pub struct ElfHeader {
     /// Defines whether the file is big or little endian
     /// true correspond to big endian, false otherwise
diff --git a/src/simulator/mem_cmp.rs b/src/simulator/mem_cmp.rs
index 64d5942..31e5a0f 100644
--- a/src/simulator/mem_cmp.rs
+++ b/src/simulator/mem_cmp.rs
@@ -1,4 +1,4 @@
-//! # mem_cmp
+//! # Memory Comparator
 //!
 //! This module contains a MemChecker.
 //!
diff --git a/src/simulator/mmu.rs b/src/simulator/mmu.rs
index b97313d..b91ace3 100644
--- a/src/simulator/mmu.rs
+++ b/src/simulator/mmu.rs
@@ -1,8 +1,8 @@
-//! # mmu
+//! # MMU
 //!
 //! This module contains a MMU implementation
 //!
-//! This part isn't tested and integrated to BurritOS because of the lack of pagination implementation
+//! This part isn't tested nor integrated to BurritOS because of the lack of pagination implementation
 //!
 //!
 
diff --git a/src/simulator/translationtable.rs b/src/simulator/translationtable.rs
index f0d7091..9dfbaa2 100644
--- a/src/simulator/translationtable.rs
+++ b/src/simulator/translationtable.rs
@@ -1,23 +1,35 @@
-//Nombre maximum de correspondances dans une table des pages
-//Cette donnée devra a terme etre recupérée depuis un fichier de configuration
+//! # Translation Table
+//!
+//! This module implement a trnslation table used for fot the MMU Emulator
+//!
+//! This part isn't tested nor integrated to BurritOS,
+//! but will be useful in the futur when the pagination will be implemented.
+//!
+//! It contains:
+//! - all the setters and getters for translation table
+//! - modificaters of table values
+
+
+/// Maximum number in a Page Table
+/// For a futur evolution of program, this value should be load from a configuration file
 const MaxVirtPages : u64 = 200000;
 
-
-/* Une table de correspondance propre à un processus
-*  Une variable de type TranslationTable devra etre possédée par un objet de type Process
- */
+/// Translation Table corresponding to a process
+/// An iteration of type TranslationTable should be possesses by an oject of type Process
 pub struct TranslationTable{
-    //capacité de cette table <=> nombre de correspondances possibles
-    //A voir si cette donnée doit etre immuable
+    /// Table size <=> nb of possible translation
     pub maxNumPages : u64,
 
-    //la table en question
-    //Vec implemente le trait Index, donc un bon choix
+    ///The table *Vec impemente Index Trait*
     pub pageTable : Vec<PageTableEntry>
 }
 
 impl TranslationTable {
 
+    /// TranslationTable constructor
+    ///
+    /// ### Return
+    /// TranslationTable with an empty Vector
     pub fn create() -> TranslationTable {
 
         let mut tmp_vec : Vec<PageTableEntry> = Vec::new();