From e7da4072e50950eca313ee43da0f62964ff58218 Mon Sep 17 00:00:00 2001
From: Ludovic 'Archivist' Lagouardette <ludovic@nekoit.xyz>
Date: Fri, 9 Apr 2021 15:31:01 +0200
Subject: [PATCH] Docs

---
 include/gp/ipc/bottleneck.hpp                 |  5 +++
 include/gp/system/process_data.hpp            | 44 ++++++++++++-------
 include/gp/system/scheduler.hpp               |  3 ++
 .../utils/allocators/bottleneck_allocator.hpp |  3 ++
 4 files changed, 40 insertions(+), 15 deletions(-)

diff --git a/include/gp/ipc/bottleneck.hpp b/include/gp/ipc/bottleneck.hpp
index 8928893..e57f2ce 100644
--- a/include/gp/ipc/bottleneck.hpp
+++ b/include/gp/ipc/bottleneck.hpp
@@ -5,6 +5,11 @@
 #include "gp_config.hpp"
 
 namespace gp {
+    /**
+     * @brief CADR lock_guard for generic locking mechanisms
+     * 
+     * @tparam T 
+     */
     template<typename T>
     class lock_guard {
         T& ref;
diff --git a/include/gp/system/process_data.hpp b/include/gp/system/process_data.hpp
index 2f7388a..ff68864 100644
--- a/include/gp/system/process_data.hpp
+++ b/include/gp/system/process_data.hpp
@@ -12,6 +12,9 @@
 namespace gp {
 	namespace system {
 
+		/**
+		 * @brief Represent the different execution states a process can be in
+		 */
 		enum class process_status {
 			inactive = 0,
 			running = 1,
@@ -20,27 +23,38 @@ namespace gp {
 			zombie = 4
 		};
 
+		/**
+		 * @brief A process ID type
+		 */
 		using pid_t = size_t;
 
+		/**
+		 * @brief Represent and manages all the process info the scheduler doesn't need to be aware of
+		 *
+		 * Anything thread local is part of that
+		 */
 		struct base_process_info {
-			virtual void initialize() {}
-			virtual void checkpoint() {}
-			virtual void restore() {}
-			virtual void switch_in() {}
-			virtual void switch_out() {}
-			virtual void cleanup() {}
-			virtual ~base_process_info() {}
+			virtual void initialize() {} //< An initializer
+			virtual void checkpoint() {} //< Creates a checkpoint if the feature is available 
+			virtual void restore() {} //< Restores a checkpoint if the feature is available
+			virtual void switch_in() {} //< Called as the process is resuming
+			virtual void switch_out() {} //< Called as the process is paused
+			virtual void cleanup() {} //< Called before the process get destroyed
+			virtual ~base_process_info() {} //< Called as the process is destroyed
 		};
 
+		/**
+		 * @brief Represents the data used for scheduling and managing a process resources.
+		 */
 		struct process_data{
-			pid_t pid;
-			gp::function<void()> fn;
-			void* stack;
-			size_t stack_sz;
-			gp::system::process_status state;
-			std::atomic_bool is_running;
-			[[no_unique_address]] gp::system::specifics::platform_data specifics;
-			gp::unique_ptr<base_process_info> info;
+			pid_t pid; //< The current pid
+			gp::function<void()> fn; //< Whatever there is to execute
+			void* stack; //< The stack lower bound pointer
+			size_t stack_sz; //< The stack size in bytes
+			gp::system::process_status state; //< The current process' state
+			std::atomic_bool is_running; //< Whenever the process is currently using execution time
+			[[no_unique_address]] gp::system::specifics::platform_data specifics; //< The special bits used to handle context switching
+			gp::unique_ptr<base_process_info> info; //< Other data related to processes but not to scheduling
 
 			process_data(gp::function<void()> _fn, void* _stack, size_t _stack_sz, gp::unique_ptr<base_process_info>&& _info) 
 			: fn(_fn)
diff --git a/include/gp/system/scheduler.hpp b/include/gp/system/scheduler.hpp
index b0d1370..539ac23 100644
--- a/include/gp/system/scheduler.hpp
+++ b/include/gp/system/scheduler.hpp
@@ -8,6 +8,9 @@ namespace gp {
 	namespace system {
 		class system;
 
+		/**
+		 * @brief The class that handles the scheduling globally in a system
+		 */
 		struct scheduler {
 			task_queue::node_ptr previous;
 			task_queue::node_ptr current;
diff --git a/include/gp/utils/allocators/bottleneck_allocator.hpp b/include/gp/utils/allocators/bottleneck_allocator.hpp
index 80cc44a..d3b5bdc 100644
--- a/include/gp/utils/allocators/bottleneck_allocator.hpp
+++ b/include/gp/utils/allocators/bottleneck_allocator.hpp
@@ -4,6 +4,9 @@
 #include "gp/ipc/bottleneck.hpp"
 
 namespace gp {
+    /**
+     * @brief A front to make allocators thread safe
+     */
     class bottleneck_allocator_front : public allocator {
         allocator& backend;
         fast_bottleneck lock;