From e430a62c358918d9332f12a00394f69e891042d7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9mi=20Rativel?=
 <remi.rativel@etudiant.univ-rennes1.fr>
Date: Sun, 14 May 2023 23:51:15 +0200
Subject: [PATCH] Kernel documentation. Still need to do thread.rs

---
 src/kernel/exception.rs |  5 +++++
 src/kernel/mgerror.rs   |  8 ++++++++
 src/kernel/mod.rs       |  6 ++++++
 src/kernel/synch.rs     | 29 ++++++++++++++++++++++-------
 src/kernel/thread.rs    |  3 +++
 5 files changed, 44 insertions(+), 7 deletions(-)

diff --git a/src/kernel/exception.rs b/src/kernel/exception.rs
index 45fb0c1..4d8cf21 100644
--- a/src/kernel/exception.rs
+++ b/src/kernel/exception.rs
@@ -1,3 +1,8 @@
+//! # Exceprions
+//!
+//! This module Enum the constant values of the exceptions.
+//! They are used to stop the system to execute some opperation
+
 use std::{cell::RefCell, rc::Rc};
 
 use crate::{simulator::{machine::{ExceptionType, Machine}, error::{MachineOk, MachineError}}};
diff --git a/src/kernel/mgerror.rs b/src/kernel/mgerror.rs
index dfe83c8..751284e 100644
--- a/src/kernel/mgerror.rs
+++ b/src/kernel/mgerror.rs
@@ -1,3 +1,11 @@
+//! # Error Code
+//!
+//! This module enumerate the possibles error code who could get in a function
+//!
+//! **Basic Usage:*
+//!
+//! Result<YourSuccessStruct, **ErrorCode**
+
 #![allow(unused, clippy::missing_docs_in_private_items)]
 /// Error enum, use it with Result<YourSucessStruct, **ErrorCode**>
 pub enum ErrorCode {
diff --git a/src/kernel/mod.rs b/src/kernel/mod.rs
index df9b60d..a072709 100644
--- a/src/kernel/mod.rs
+++ b/src/kernel/mod.rs
@@ -1,3 +1,9 @@
+//! # Kernel
+//!
+//! This module contains all the tool required for the kernel to work.
+//!
+//! Currently it contains the scheduling and synchroisation tools, but it will contains the tools
+//! required Memory gestion, Files gestion and peripheral pilots.
 pub mod process;
 pub mod thread;
 pub mod mgerror;
diff --git a/src/kernel/synch.rs b/src/kernel/synch.rs
index a1472e5..2b5cb88 100644
--- a/src/kernel/synch.rs
+++ b/src/kernel/synch.rs
@@ -1,3 +1,11 @@
+//! # Synchronisation
+//!
+//! This module contains some scheduling and synchronisation utilities:
+//! - **Semaphore**
+//! - **Lock**
+//!
+//! Conditions aren't implemented currently
+
 use crate::utility::list::List;
 use crate::kernel::thread::Thread;
 use crate::simulator::interrupt::InterruptStatus::InterruptOff;
@@ -6,20 +14,21 @@ use std::cell::RefCell;
 use std::rc::Rc;
 use super::thread_manager::ThreadManager;
 
-///     Structure of a Semaphore used for synchronisation
+/// Structure of a Semaphore used for synchronisation.
+/// It use a counter to determine the number of thread that can be executed simultaneously.
 #[derive(PartialEq)]
 pub struct Semaphore {
 
-    /// Counter of simultanous Semaphore
+    /// Counter of simultaneous Semaphore
     pub counter:i32,
-    /// QUeue of Semaphore waiting to be exucated
+    /// QUeue of Semaphore waiting to be executed
     pub waiting_queue:List<Rc<RefCell<Thread>>>,
 
 }
 
 impl Semaphore {
 
-    ///     Initializes a semaphore, so that it can be used for synchronization.
+    /// Initializes a semaphore, so that it can be used for synchronization.
     ///
     ///  ### Parameters
     /// - *counter* initial value of counter
@@ -49,7 +58,7 @@ pub struct Lock {
 impl Lock {
 
     ///    Initialize a Lock, so that it can be used for synchronization.
-    /// The lock is initialy free
+    /// The lock is initially free
     ///
     /// ### Parameters
     /// - **thread_manager** Thread manager which managing threads
@@ -72,7 +81,7 @@ impl Lock {
         let old_status = machine.interrupt.set_status(InterruptOff);
         if self.free {
             self.free = false;
-            self.owner = Option::Some(match thread_manager.get_g_current_thread() {
+            self.owner = Some(match thread_manager.get_g_current_thread() {
                 Some(th) => {
                     Rc::clone(&th)
                 },
@@ -128,8 +137,14 @@ impl Lock {
         machine.interrupt.set_status(old_status);
     }
 
-    ///    True if the current thread holds this lock.
+    /// Say if the lock is held by the current thread
     /// Useful for checking in Release, and in Condition operations below.
+    /// ### Parameters
+    /// - **self** The current lock
+    /// - **thread-manager** The thread manager present in the system
+    /// ### Return
+    /// True if the current thread holds this lock.
+
     pub fn held_by_current_thread(&mut self, thread_manager: &mut ThreadManager) -> bool {
         match &self.owner {
             Some(x) => 
diff --git a/src/kernel/thread.rs b/src/kernel/thread.rs
index d0bdc3e..91a4583 100644
--- a/src/kernel/thread.rs
+++ b/src/kernel/thread.rs
@@ -1,3 +1,6 @@
+//! # Thread
+//!
+//!
 use std::{rc::Rc, cell::RefCell};
 
 use super::{process::Process, thread_manager::ThreadRef};