Merge remote-tracking branch 'git/feature/advanced-organ-docs'

.gitignore

@@ -61,3 +61,6 @@
 # Doxygen
 /docs/xml/
 /docs/latex/
+
+# Custom build output
+/doc_build_test/

docs/conf.py

@@ -16,6 +16,7 @@ release = '1.0'
 
 extensions = [
     'breathe',
+    'sphinx.ext.graphviz',
 ]
 
 templates_path = ['_templates']

include/MedicalLib/Bladder.h

@@ -13,7 +13,80 @@ enum class MicturitionState {
 };
 
 /**
- * @brief Represents the Bladder, which stores urine.
+ * @brief Represents the Bladder, simulating the storage and expulsion of urine.
+ *
+ * @section bio_sec Biological Overview
+ * The urinary bladder is a muscular, hollow organ that sits in the pelvic floor. Its primary
+ * function is to collect and store urine produced by the kidneys. Urine enters the bladder
+ * via two tubes called ureters.
+ *
+ * The wall of the bladder contains a muscle called the detrusor muscle, which can relax to
+ * allow the bladder to stretch and fill, and contract to expel urine. The exit from the
+ * bladder is controlled by two sphincters. The process of urinating is called micturition.
+ * As the bladder fills, stretch receptors in its wall send signals to the brain, creating
+ * the urge to urinate.
+ *
+ * @section model_sec Code Simulation
+ * This `Bladder` class models the fill-void cycle of the urinary bladder.
+ *
+ * @subsection state_model_sec State-Based Model
+ * The simulation is managed by the `MicturitionState` enum, which tracks the current phase:
+ * - `FILLING`: The bladder is passively collecting urine from the kidneys.
+ * - `FULL`: The bladder has reached a capacity where the urge to void is strong.
+ * - `VOIDING`: The bladder is contracting to expel urine.
+ *
+ * The `addUrine()` method allows the `Kidneys` model to add to the bladder's volume. The `update()`
+ * method simulates the increase in pressure as volume increases and handles the state transitions.
+ *
+ * @subsection micturition_state_sec Micturition Cycle Diagram
+ * This diagram shows the state transitions of the bladder as it fills and voids.
+ *
+ * @dot
+ * digraph MicturitionCycle {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     FILLING -> FULL [label="volume > threshold"];
+ *     FULL -> VOIDING [label="voiding signal"];
+ *     VOIDING -> FILLING [label="volume = 0"];
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to simulate urine being added to the bladder and observe
+ * the change in its state.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Bladder.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Bladder object
+ *     Bladder bladder(1);
+ *     std::cout << "Initial State: " << bladder.getSummary() << std::endl;
+ *
+ *     // Add urine from the kidneys over time
+ *     std::cout << "\nKidneys are producing urine..." << std::endl;
+ *     for (int i = 0; i < 300; ++i) {
+ *         bladder.addUrine(1.0); // Add 1mL of urine
+ *         bladder.update(patient, 1.0);
+ *     }
+ *     std::cout << "State after adding 300mL: " << bladder.getSummary() << std::endl;
+ *
+ *     // Add more urine to reach the 'FULL' state
+ *     for (int i = 0; i < 200; ++i) {
+ *         bladder.addUrine(1.0);
+ *         bladder.update(patient, 1.0);
+ *     }
+ *     std::cout << "State after adding another 200mL: " << bladder.getSummary() << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Bladder : public Organ {
 public:

include/MedicalLib/Brain.h

@@ -16,7 +16,105 @@ struct BrainRegion {
 };
 
 /**
- * @brief Represents the Brain organ with a more detailed physiological model.
+ * @brief Represents the Brain organ, simulating neurological vitals and activity.
+ *
+ * @section bio_sec Biological Overview
+ * The brain is the command center of the nervous system, controlling thought, memory, emotion,
+ * touch, motor skills, vision, breathing, temperature, hunger, and every process that regulates
+ * our body. It is a complex organ composed of several distinct regions, each with specialized
+- * functions.
++ * functions. The major parts include:
+ * - **Frontal Lobe**: Associated with reasoning, planning, parts of speech, movement, emotions, and problem-solving.
+ * - **Parietal Lobe**: Manages perception of stimuli related to touch, pressure, temperature, and pain.
+ * - **Temporal Lobe**: Involved in perception and recognition of auditory stimuli, memory, and speech.
+ * - **Occipital Lobe**: Primarily responsible for vision.
+ * - **Cerebellum**: Crucial for coordinating voluntary movements, posture, balance, and speech.
+ *
+ * Maintaining adequate blood flow is critical for brain health. Two key metrics are:
+ * - **Intracranial Pressure (ICP)**: The pressure inside the skull.
+ * - **Cerebral Perfusion Pressure (CPP)**: The net pressure gradient causing blood flow to the brain.
+ *
+ * @section model_sec Code Simulation
+ * This `Brain` class models the brain's high-level physiological state and its influence on
+ * the body's autonomic systems.
+ *
+ * @subsection neuro_vitals_sec Neurological Vitals
+ * The simulation tracks several key neurological vitals:
+ * - **Glasgow Coma Scale (GCS)**: A simplified score representing the level of consciousness,
+ *   accessible via `getGCS()`.
+ * - **Intracranial Pressure (ICP)**: A simulated pressure within the skull, retrieved with
+ *   `getIntracranialPressure()`.
+ * - **Cerebral Perfusion Pressure (CPP)**: Calculated based on ICP and Mean Arterial Pressure,
+ *   available through `getCerebralPerfusionPressure()`.
+ * - **EEG Waveform**: The class generates a simplified electroencephalogram (EEG) waveform,
+ *   which can be accessed with `getEegWaveform()`.
+ *
+ * @subsection region_model_sec Regional Activity Model
+ * The major lobes and the cerebellum are modeled as `BrainRegion` structs, each with its own
+ * metabolic activity level and blood flow. The `update()` method adjusts these values over time.
+ *
+ * @subsection brain_diagram_sec Brain Regions Diagram
+ * This diagram shows the major brain regions simulated by this class.
+ *
+ * @dot
+ * digraph BrainRegions {
+ *     node [shape=box, style=rounded];
+ *
+ *     Brain [label="Brain", shape=ellipse];
+ *
+ *     subgraph cluster_Cerebrum {
+ *         label="Cerebrum (Lobes)";
+ *         style=filled;
+ *         color=lightblue;
+ *         Frontal [label="Frontal Lobe"];
+ *         Parietal [label="Parietal Lobe"];
+ *         Temporal [label="Temporal Lobe"];
+ *         Occipital [label="Occipital Lobe"];
+ *     }
+ *
+ *     Cerebellum [label="Cerebellum", style=filled, color=lightpink];
+ *
+ *     Brain -> Frontal;
+ *     Brain -> Parietal;
+ *     Brain -> Temporal;
+ *     Brain -> Occipital;
+ *     Brain -> Cerebellum;
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to create a `Brain` instance and monitor its state.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Brain.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Brain object
+ *     Brain brain(1);
+ *
+ *     // Simulate for 5 seconds
+ *     std::cout << "Simulating Brain for 5 seconds..." << std::endl;
+ *     for (int i = 0; i < 5; ++i) {
+ *         // In a real simulation, the patient's heart would update the MAP
+ *         patient.setVital("MeanArterialPressure", 85.0); // Example MAP
+ *         brain.update(patient, 1.0); // Update by 1.0 second
+ *         std::cout << "Time: " << i + 1 << "s, " << brain.getSummary() << std::endl;
+ *     }
+ *
+ *     // Retrieve specific final vitals
+ *     std::cout << "\n--- Simulation Results ---" << std::endl;
+ *     std::cout << "Final GCS: " << brain.getGCS() << std::endl;
+ *     std::cout << "Final ICP: " << brain.getIntracranialPressure() << " mmHg" << std::endl;
+ *     std::cout << "Final CPP: " << brain.getCerebralPerfusionPressure() << " mmHg" << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Brain : public Organ {
 public:

include/MedicalLib/Esophagus.h

@@ -22,7 +22,81 @@ struct Bolus {
 };
 
 /**
- * @brief Represents the Esophagus with a more detailed physiological model.
+ * @brief Represents the Esophagus, simulating the transport of food via peristalsis.
+ *
+ * @section bio_sec Biological Overview
+ * The esophagus is a muscular tube that connects the pharynx (throat) to the stomach. Its sole
+ * function in the digestive system is to transport food and liquid from the mouth to the stomach.
+ *
+ * This transport is achieved through a process called **peristalsis**, which is a series of
+ * wave-like muscle contractions that move food along the digestive tract. When a person swallows,
+ * the esophagus muscles contract behind the chewed food (bolus) and relax in front of it, pushing
+ * it downward. At the bottom, the lower esophageal sphincter (LES) relaxes to allow the food to
+ * enter the stomach and then closes to prevent stomach contents from flowing back up.
+ *
+ * @section model_sec Code Simulation
+ * This `Esophagus` class models the process of swallowing and peristalsis.
+ *
+ * @subsection state_model_sec State-Based Model
+ * The simulation is managed by the `PeristalsisState` enum, which tracks the current muscle activity:
+ * - `IDLE`: No swallowing is in progress.
+ * - `CONTRACTING`: The muscle is actively contracting to push a bolus.
+ * - `RELAXING`: The muscle is relaxing after a contraction.
+ *
+ * A mass of food is represented by the `Bolus` struct. The process begins when `initiateSwallow()`
+ * is called, which creates a new bolus. The `update()` method then simulates the movement of this
+ * bolus down the esophagus's length until it is delivered to the stomach.
+ *
+ * @subsection peristalsis_flow_sec Peristalsis Flow Diagram
+ * This diagram shows the journey of a food bolus from the throat to the stomach.
+ *
+ * @dot
+ * digraph PeristalsisFlow {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     Pharynx [label="Pharynx (Throat)"];
+ *     Esophagus [label="Esophagus\n(Peristaltic Wave)"];
+ *     Stomach [label="Stomach"];
+ *
+ *     Pharynx -> Esophagus [label="swallow()"];
+ *     Esophagus -> Stomach [label="LES opens"];
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to simulate swallowing a bolus of food.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Esophagus.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create an Esophagus object
+ *     Esophagus esophagus(1);
+ *     std::cout << "Initial State: " << esophagus.getSummary() << std::endl;
+ *
+ *     // Initiate a swallow
+ *     std::cout << "\nSwallowing a 15mL bolus..." << std::endl;
+ *     esophagus.initiateSwallow(15.0);
+ *
+ *     // Simulate the bolus moving down the esophagus
+ *     for (int i = 0; i < 10; ++i) {
+ *         esophagus.update(patient, 1.0); // Simulate 1 second
+ *         std::cout << "Time: " << i + 1 << "s, " << esophagus.getSummary() << std::endl;
+ *         if (!esophagus.isSwallowing()) {
+ *             std::cout << "Bolus has reached the stomach." << std::endl;
+ *             break;
+ *         }
+ *     }
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Esophagus : public Organ {
 public:

include/MedicalLib/Gallbladder.h

@@ -12,7 +12,80 @@ enum class GallbladderState {
 };
 
 /**
- * @brief Represents the Gallbladder, which stores and concentrates bile.
+ * @brief Represents the Gallbladder, which stores, concentrates, and releases bile.
+ *
+ * @section bio_sec Biological Overview
+ * The gallbladder is a small, pear-shaped organ located beneath the liver. Its main purpose is
+ * to store and concentrate bile, a digestive fluid produced by the liver. Bile is essential
+ * for the digestion of fats.
+ *
+ * After being produced by the liver, bile travels to the gallbladder where it is stored. The
+ * gallbladder lining absorbs water from the bile, making it more concentrated. When fatty food
+ * enters the small intestine, a hormone called cholecystokinin (CCK) is released, signaling the
+ * gallbladder to contract and release the concentrated bile into the duodenum (the first part
+ * of the small intestine).
+ *
+ * @section model_sec Code Simulation
+ * This `Gallbladder` class models the storage and release cycle of bile.
+ *
+ * @subsection state_model_sec State-Based Model
+ * The simulation is managed by the `GallbladderState` enum, which has two states:
+ * - `STORING`: The default state, where the gallbladder is passively filling with bile from the liver.
+ * - `CONTRACTING`: Triggered by a simulated signal (e.g., presence of fats), causing the
+ *   gallbladder to release bile.
+ *
+ * The `storeBile()` method is used to add bile from the liver, and `releaseBile()` simulates the
+ * contraction, returning the volume of bile ejected. The model also tracks the `bileConcentrationFactor`.
+ *
+ * @subsection bile_flow_sec Bile Flow Diagram
+ * This diagram shows the flow of bile from the liver to the gallbladder and then to the intestine.
+ *
+ * @dot
+ * digraph BileFlow {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     Liver [label="Liver\n(Produces Bile)"];
+ *     Gallbladder [label="Gallbladder\n(Stores & Concentrates Bile)"];
+ *     Intestine [label="Small Intestine\n(Duodenum)"];
+ *
+ *     Liver -> Gallbladder [label=" stores"];
+ *     Gallbladder -> Intestine [label=" releases upon signal"];
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to simulate the gallbladder storing and then releasing bile.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Gallbladder.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Gallbladder object
+ *     Gallbladder gallbladder(1);
+ *     std::cout << "Initial State: " << gallbladder.getSummary() << std::endl;
+ *
+ *     // Store some bile from the liver
+ *     std::cout << "\nStoring 10mL of bile..." << std::endl;
+ *     gallbladder.storeBile(10.0);
+ *     std::cout << "State after storing: " << gallbladder.getSummary() << std::endl;
+ *
+ *     // Simulate the gallbladder contracting and releasing bile
+ *     std::cout << "\nFood detected! Releasing bile..." << std::endl;
+ *     // In a full simulation, the update() method would trigger the state change.
+ *     // We'll call releaseBile() directly for this example.
+ *     double released = gallbladder.releaseBile(5.0); // Simulate 5s of release
+ *     std::cout << "Released " << released << " mL of bile." << std::endl;
+ *     std::cout << "Final State: " << gallbladder.getSummary() << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Gallbladder : public Organ {
 public:

include/MedicalLib/Heart.h

@@ -40,6 +40,113 @@ struct Chamber {
 
 /**
  * @brief Represents the Heart organ, with detailed mechanical and electrical simulation.
+ *
+ * @section bio_sec Biological Overview
+ * The heart is a muscular organ responsible for pumping blood throughout the circulatory system.
+ * It is divided into four chambers: two upper atria and two lower ventricles. The right side
+ * of the heart handles deoxygenated blood, while the left side handles oxygenated blood.
+ *
+ * - **Deoxygenated blood** from the body enters the **Right Atrium**.
+ * - It is pumped to the **Right Ventricle** through the **Tricuspid Valve**.
+ * - The Right Ventricle pumps the blood to the lungs through the **Pulmonary Valve**.
+ * - **Oxygenated blood** from the lungs enters the **Left Atrium**.
+ * - It is pumped to the **Left Ventricle** through the **Mitral Valve**.
+ * - The Left Ventricle pumps the oxygenated blood to the rest of the body through the **Aortic Valve**.
+ *
+ * This entire sequence is known as the cardiac cycle, which involves two main phases:
+ * 1.  **Diastole**: The relaxation phase, where chambers fill with blood.
+ * 2.  **Systole**: The contraction phase, where chambers pump blood out.
+ *
+ * @section model_sec Code Simulation
+ * This `Heart` class provides a detailed simulation of both the mechanical and electrical functions
+ * of the human heart.
+ *
+ * @subsection mech_model_sec Mechanical Model
+ * The four chambers and four primary valves are modeled using the `Chamber` and `Valve` structs.
+ * The `update()` function drives the simulation forward in time, calculating changes in chamber
+ * volume and pressure based on the current phase of the cardiac cycle (systole or diastole).
+ * Key outputs of the mechanical simulation include:
+ * - **Ejection Fraction**: The percentage of blood pumped out of the left ventricle with each beat.
+ *   Calculated by `getEjectionFraction()`.
+ * - **Aortic Pressure**: Represents the systemic blood pressure. Retrieved with `getAorticPressure()`.
+ *
+ * @subsection elec_model_sec Electrical Model
+ * The class also simulates the heart's electrical activity, which is observable via an
+ * electrocardiogram (EKG). The `simulateEkgWaveform()` function generates a realistic EKG signal
+ * based on the cardiac cycle's timing. The number of EKG leads can be configured in the constructor.
+ * The generated data can be accessed using `getEkgData()`.
+ *
+ * @subsection a_graph_sec Blood Flow Diagram
+ * The following diagram illustrates the path of blood through the heart's chambers and valves.
+ *
+ * @dot
+ * digraph BloodFlow {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     subgraph cluster_Deoxygenated {
+ *         label="Deoxygenated Blood (Pulmonary Circuit)";
+ *         style=filled;
+ *         color=lightblue;
+ *         Body [label="Vena Cava\n(from Body)"];
+ *         RA [label="Right Atrium"];
+ *         RV [label="Right Ventricle"];
+ *         Lungs_In [label="Pulmonary Artery\n(to Lungs)"];
+ *         Body -> RA [label=" Enters"];
+ *         RA -> RV [label=" Tricuspid Valve"];
+ *         RV -> Lungs_In [label=" Pulmonary Valve"];
+ *     }
+ *
+ *     subgraph cluster_Oxygenated {
+ *         label="Oxygenated Blood (Systemic Circuit)";
+ *         style=filled;
+ *         color=lightpink;
+ *         Lungs_Out [label="Pulmonary Vein\n(from Lungs)"];
+ *         LA [label="Left Atrium"];
+ *         LV [label="Left Ventricle"];
+ *         Aorta [label="Aorta\n(to Body)"];
+ *         Lungs_Out -> LA [label=" Enters"];
+ *         LA -> LV [label=" Mitral Valve"];
+ *         LV -> Aorta [label=" Aortic Valve"];
+ *     }
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * Here is a simple example of how to create a `Heart` object, simulate it over time,
+ * and retrieve data.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Heart.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Heart with 12 EKG leads
+ *     Heart heart(1, 12);
+ *
+ *     // Set a baseline heart rate
+ *     heart.setHeartRate(75.0);
+ *
+ *     // Simulate the heart for 5 seconds
+ *     std::cout << "Simulating Heart for 5 seconds..." << std::endl;
+ *     for (int i = 0; i < 5; ++i) {
+ *         heart.update(patient, 1.0); // Update by 1.0 second
+ *         std::cout << "Time: " << i + 1 << "s, " << heart.getSummary() << std::endl;
+ *     }
+ *
+ *     // Retrieve specific metrics from the simulation
+ *     std::cout << "\n--- Simulation Results ---" << std::endl;
+ *     std::cout << "Final Measured Heart Rate: " << heart.getHeartRate() << " bpm" << std::endl;
+ *     std::cout << "Final Ejection Fraction: " << heart.getEjectionFraction() << "%" << std::endl;
+ *     std::cout << "Final Aortic Pressure: " << heart.getAorticPressure() << " mmHg" << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Heart : public Organ {
 public:

include/MedicalLib/Intestines.h

@@ -19,7 +19,96 @@ struct IntestinalSegment {
 };
 
 /**
- * @brief Represents the Intestines (Small and Large) with a more detailed model.
+ * @brief Represents the Intestines (Small and Large), simulating final digestion and absorption.
+ *
+ * @section bio_sec Biological Overview
+ * The intestines are a crucial part of the digestive tract where most of the absorption of
+ * nutrients and water happens. They are divided into two main parts:
+ *
+ * - **Small Intestine**: A long, coiled tube where the majority of digestion and nutrient
+ *   absorption takes place. It receives chyme from the stomach, along with bile from the
+ *   gallbladder and digestive enzymes from the pancreas. It has three segments:
+ *   1.  **Duodenum**: The first section, where chyme is mixed with bile and enzymes.
+ *   2.  **Jejunum**: The middle section, where most nutrient absorption occurs.
+ *   3.  **Ileum**: The final section, which absorbs any remaining nutrients.
+ *
+ * - **Large Intestine (Colon)**: A shorter, wider tube that absorbs water and electrolytes from
+ *   the remaining indigestible food matter and then passes useless waste material from the body.
+ *
+ * @section model_sec Code Simulation
+ * This `Intestines` class models the passage of chyme through the various intestinal segments.
+ *
+ * @subsection segment_model_sec Segment-Based Model
+ * The small and large intestines are modeled as a series of `IntestinalSegment` structs, each
+ * with its own properties for motility and absorption rates. The `update()` method simulates
+ * the movement and processing of chyme through these segments over time.
+ *
+ * @subsection interaction_sec Interaction with Other Organs
+ * The model is designed to work with other digestive organs:
+ * - `receiveChyme()`: Takes the output from the Stomach.
+ * - `receiveBile()`: Takes bile from the Gallbladder to aid in fat digestion.
+ * - `receiveEnzymes()`: Takes enzymes from the Pancreas to break down macromolecules.
+ *
+ * @subsection intestines_flow_sec Digestive Flow Diagram
+ * The following diagram shows the path of chyme as it enters from the stomach and moves
+ * through the different segments of the intestines.
+ *
+ * @dot
+ * digraph IntestinesFlow {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     Stomach [label="Stomach"];
+ *     Duodenum [label="Duodenum"];
+ *     Jejunum [label="Jejunum"];
+ *     Ileum [label="Ileum"];
+ *     Colon [label="Colon (Large Intestine)"];
+ *     Waste [label="Waste Exit"];
+ *
+ *     Pancreas [shape=ellipse, style=filled, color=lightgrey];
+ *     Gallbladder [shape=ellipse, style=filled, color=lightgrey];
+ *
+ *     Stomach -> Duodenum [label="Chyme"];
+ *     Pancreas -> Duodenum [label="Enzymes"];
+ *     Gallbladder -> Duodenum [label="Bile"];
+ *     Duodenum -> Jejunum;
+ *     Jejunum -> Ileum;
+ *     Ileum -> Colon;
+ *     Colon -> Waste;
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to simulate the intestines receiving chyme from the stomach.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Intestines.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create an Intestines object
+ *     Intestines intestines(1);
+ *     std::cout << "Initial State: " << intestines.getSummary() << std::endl;
+ *
+ *     // Receive chyme from the stomach
+ *     std::cout << "\nReceiving 200mL of chyme..." << std::endl;
+ *     intestines.receiveChyme(200.0);
+ *     std::cout << "State after receiving chyme: " << intestines.getSummary() << std::endl;
+ *
+ *     // Simulate digestion and absorption over time
+ *     std::cout << "\nSimulating for 1 hour..." << std::endl;
+ *     for (int i = 0; i < 60; ++i) {
+ *         intestines.update(patient, 60.0); // Simulate 1 minute
+ *     }
+ *     std::cout << "State after 1 hour: " << intestines.getSummary() << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Intestines : public Organ {
 public:

include/MedicalLib/Kidneys.h

@@ -14,7 +14,91 @@ struct Nephron {
 };
 
 /**
- * @brief Represents the Kidneys, responsible for filtering blood and producing urine.
+ * @brief Represents the Kidneys, simulating blood filtration, urine production, and electrolyte balance.
+ *
+ * @section bio_sec Biological Overview
+ * The kidneys are a pair of bean-shaped organs that perform several vital functions. Their primary
+ * role is to filter waste products, excess water, and other impurities from the blood. These
+ * waste products are converted into urine, which flows to the bladder to be excreted.
+ *
+ * Each kidney contains millions of tiny filtering units called **nephrons**. Blood enters the
+ * nephron, where waste is filtered out and essential substances are reabsorbed back into the blood.
+ *
+ * Key functions of the kidneys include:
+ * - **Waste Excretion**: Filtering out urea, creatinine, and other metabolic wastes.
+ * - **Electrolyte Balance**: Regulating the levels of sodium, potassium, and other electrolytes.
+ * - **Blood Pressure Regulation**: Producing the enzyme renin, which plays a key role in the
+ *   renin-angiotensin-aldosterone system that controls blood pressure.
+ * - **Acid-Base Balance**: Maintaining the pH of the blood within a narrow range.
+ *
+ * The **Glomerular Filtration Rate (GFR)** is a key measure of kidney function, representing the
+ * volume of fluid filtered from the blood per unit time.
+ *
+ * @section model_sec Code Simulation
+ * This `Kidneys` class models the filtration and regulatory functions of the kidneys.
+ *
+ * @subsection func_model_sec Functional Model
+ * The kidney's filtering capacity is represented by a vector of `Nephron` structs. Each nephron
+ * has a specific `filtrationEfficiency`. The `update()` method simulates the ongoing process of
+ * blood filtration, calculating urine output and changes in blood chemistry.
+ *
+ * @subsection vitals_sec Simulated Renal Vitals
+ * The simulation tracks several key indicators of renal function:
+ * - **GFR**: The Glomerular Filtration Rate, a primary indicator of kidney health, accessible via `getGfr()`.
+ * - **Urine Output**: The rate of urine production, retrieved with `getUrineOutputRate()`.
+ * - **Electrolytes**: Simulated levels of blood sodium (`getBloodSodium()`) and potassium (`getBloodPotassium()`).
+ * - **Renin**: The secretion rate of renin, a key hormone for blood pressure control, available
+ *   through `getReninSecretionRate()`.
+ *
+ * @subsection kidney_flow_sec Kidney Filtration Flow
+ * The following diagram illustrates the high-level flow of blood through the kidneys for filtration.
+ *
+ * @dot
+ * digraph KidneyFlow {
+ *     rankdir="TB";
+ *     node [shape=record, style=rounded];
+ *
+ *     BloodIn [label="Renal Artery\n(Unfiltered Blood)"];
+ *     Kidney [label="{<n>Nephrons|Glomerular Filtration}"];
+ *     BloodOut [label="Renal Vein\n(Filtered Blood)"];
+ *     UrineOut [label="Ureter\n(Urine to Bladder)"];
+ *
+ *     BloodIn -> Kidney:n;
+ *     Kidney -> BloodOut;
+ *     Kidney -> UrineOut;
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to create a `Kidneys` object and monitor its function.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Kidneys.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Kidneys object
+ *     Kidneys kidneys(1);
+ *
+ *     // Simulate for a short period
+ *     std::cout << "Simulating Kidneys function for 1 minute..." << std::endl;
+ *     kidneys.update(patient, 60.0); // Simulate 60 seconds of activity
+ *     std::cout << kidneys.getSummary() << std::endl;
+ *
+ *     // Retrieve specific final vitals
+ *     std::cout << "\n--- Renal Function Panel ---" << std::endl;
+ *     std::cout << "GFR: " << kidneys.getGfr() << " mL/min" << std::endl;
+ *     std::cout << "Urine Output Rate: " << kidneys.getUrineOutputRate() << " mL/s" << std::endl;
+ *     std::cout << "Blood Sodium: " << kidneys.getBloodSodium() << " mEq/L" << std::endl;
+ *     std::cout << "Blood Potassium: " << kidneys.getBloodPotassium() << " mEq/L" << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Kidneys : public Organ {
 public:

include/MedicalLib/Liver.h

@@ -14,7 +14,89 @@ struct HepaticLobule {
 };
 
 /**
- * @brief Represents the Liver organ with a more detailed physiological model.
+ * @brief Represents the Liver organ, simulating metabolic and detoxification functions.
+ *
+ * @section bio_sec Biological Overview
+ * The liver is a large, essential organ located in the upper right quadrant of the abdomen. It
+ * performs a vast number of critical functions, including:
+ * - **Metabolism**: It metabolizes carbohydrates, fats, and proteins. It plays a central role in
+ *   maintaining blood glucose levels, for example through gluconeogenesis (creating glucose).
+ * - **Detoxification**: It filters the blood to remove toxins, drugs, and metabolic byproducts
+ *   like bilirubin.
+ * - **Synthesis**: It produces essential proteins, such as albumin and clotting factors. It also
+ *   produces angiotensinogen, a key hormone in blood pressure regulation.
+ * - **Bile Production**: It produces bile, a fluid that is stored in the gallbladder and is
+ *   essential for the digestion of fats in the small intestine.
+ *
+ * Liver health is often assessed by measuring the levels of liver enzymes (like ALT and AST) and
+ * bilirubin in the blood. Elevated levels can indicate liver damage or disease.
+ *
+ * @section model_sec Code Simulation
+ * This `Liver` class models the liver's key metabolic and synthetic functions.
+ *
+ * @subsection func_model_sec Functional Model
+ * The liver's vast processing capacity is represented by a collection of `HepaticLobule` structs,
+ * which are the functional units of the organ. The `update()` method simulates ongoing metabolic
+ * activity, calculating the production rates of various substances.
+ *
+ * @subsection vitals_sec Simulated Vitals and Outputs
+ * The simulation tracks several key indicators of liver function:
+ * - **Bile Production**: The rate at which bile is produced, accessible via `getBileProductionRate()`.
+ * - **Glucose Production**: The rate of gluconeogenesis, retrieved with `getGlucoseProductionRate()`.
+ * - **Liver Enzymes**: Simulated levels of ALT (`getAltLevel()`) and AST (`getAstLevel()`), which
+ *   rise in response to liver damage.
+ * - **Bilirubin**: The level of bilirubin in the blood, a marker for detoxification efficiency,
+ *   available through `getBilirubinLevel()`.
+ *
+ * @subsection liver_flow_sec Liver Blood and Bile Flow
+ * The following diagram illustrates the high-level flow of substances into and out of the liver.
+ *
+ * @dot
+ * digraph LiverFlow {
+ *     rankdir="LR";
+ *     node [shape=record, style=rounded];
+ *
+ *     Input [label="{<pv>Portal Vein (Nutrient-rich Blood)|<ha>Hepatic Artery (Oxygen-rich Blood)}"];
+ *     Liver [label="<in>Liver Processing|{Metabolism | Detoxification | Synthesis}"];
+ *     Output [label="{<hv>Hepatic Vein (Cleaned Blood to Body)|<bd>Bile Duct (Bile to Gallbladder)}"];
+ *
+ *     Input:pv -> Liver:in;
+ *     Input:ha -> Liver:in;
+ *     Liver -> Output:hv;
+ *     Liver -> Output:bd;
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to create a `Liver` object and check its functional outputs.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Liver.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Liver object
+ *     Liver liver(1);
+ *
+ *     // Simulate for a short period
+ *     std::cout << "Simulating Liver function..." << std::endl;
+ *     liver.update(patient, 10.0); // Simulate 10 seconds of activity
+ *     std::cout << liver.getSummary() << std::endl;
+ *
+ *     // Retrieve specific final vitals
+ *     std::cout << "\n--- Liver Function Tests ---" << std::endl;
+ *     std::cout << "Bile Production Rate: " << liver.getBileProductionRate() << " mL/min" << std::endl;
+ *     std::cout << "ALT Level: " << liver.getAltLevel() << " U/L" << std::endl;
+ *     std::cout << "AST Level: " << liver.getAstLevel() << " U/L" << std::endl;
+ *     std::cout << "Bilirubin Level: " << liver.getBilirubinLevel() << " mg/dL" << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Liver : public Organ {
 public:

include/MedicalLib/Lungs.h

@@ -32,7 +32,112 @@ struct Bronchus {
 };
 
 /**
- * @brief Represents the Lungs organ with a more detailed physiological model.
+ * @brief Represents the Lungs organ, simulating respiratory mechanics and gas exchange.
+ *
+ * @section bio_sec Biological Overview
+ * The lungs are the primary organs of the respiratory system, responsible for gas exchange.
+ * Air is inhaled through the trachea, which branches into two main bronchi, one for each lung.
+ * These bronchi further divide into smaller bronchioles, eventually leading to tiny air sacs
+ * called alveoli, where oxygen from the inhaled air passes into the blood and carbon dioxide
+ * from the blood is released into the air to be exhaled.
+ *
+ * The process of breathing consists of two phases:
+ * 1.  **Inspiration**: The diaphragm and intercostal muscles contract, expanding the chest cavity
+ *     and drawing air into the lungs.
+ * 2.  **Expiration**: The muscles relax, the chest cavity shrinks, and air is forced out of the lungs.
+ *
+ * The human lungs are divided into lobes; the right lung has three (upper, middle, lower) and the
+ * left lung has two (upper, lower).
+ *
+ * @section model_sec Code Simulation
+ * This `Lungs` class models the physiological functions of the lungs, including the mechanics of
+ * breathing and the resulting changes in vital signs.
+ *
+ * @subsection resp_mech_sec Respiratory Mechanics
+ * The anatomical structure is simplified into five `Lobe` structs and a main `Bronchus` struct.
+ * The `update()` method drives the respiratory cycle, which is governed by the `RespiratoryState`
+ * enum (`INSPIRATION`, `EXPIRATION`, `PAUSE`). The simulation calculates changes in lobe volume
+ * based on physiological parameters like `respirationRate` and `tidalVolume_mL`.
+ *
+ * @subsection gas_exchange_sec Gas Exchange and Vitals
+ * The simulation produces several key respiratory vital signs:
+ * - **Oxygen Saturation (SpO2)**: A measure of the oxygen level in the blood, accessible via `getOxygenSaturation()`.
+ * - **End-Tidal CO2 (etCO2)**: The concentration of carbon dioxide at the end of an exhaled breath,
+ *   retrieved with `getEndTidalCO2()`. The class also generates a continuous capnography waveform
+ *   (`getCapnographyWaveform()`).
+ * - **Tidal Volume**: The volume of air moved in a single breath, available through `getTidalVolume()`.
+ *
+ * @subsection airflow_graph_sec Airflow Diagram
+ * The following diagram shows the simplified path of air from the main bronchus to the five lobes.
+ *
+ * @dot
+ * digraph Airflow {
+ *     rankdir="LR";
+ *     node [shape=box, style=rounded];
+ *
+ *     Trachea [label="Trachea / Main Bronchus"];
+ *
+ *     subgraph cluster_RightLung {
+ *         label="Right Lung";
+ *         style=filled;
+ *         color=lightblue;
+ *         RUL [label="Right Upper Lobe"];
+ *         RML [label="Right Middle Lobe"];
+ *         RLL [label="Right Lower Lobe"];
+ *     }
+ *
+ *     subgraph cluster_LeftLung {
+ *         label="Left Lung";
+ *         style=filled;
+ *         color=lightpink;
+ *         LUL [label="Left Upper Lobe"];
+ *         LLL [label="Left Lower Lobe"];
+ *     }
+ *
+ *     Trachea -> RUL;
+ *     Trachea -> RML;
+ *     Trachea -> RLL;
+ *     Trachea -> LUL;
+ *     Trachea -> LLL;
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code demonstrates how to create a `Lungs` object, set a
+ * respiration rate, and monitor its vitals over a short period.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include <vector>
+ * #include "MedicalLib/Lungs.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Lungs object
+ *     Lungs lungs(1);
+ *
+ *     // Set a custom respiration rate
+ *     lungs.setRespirationRate(16.0); // 16 breaths per minute
+ *
+ *     // Simulate for 10 seconds
+ *     std::cout << "Simulating Lungs for 10 seconds..." << std::endl;
+ *     for (int i = 0; i < 10; ++i) {
+ *         lungs.update(patient, 1.0); // Update by 1.0 second
+ *         std::cout << "Time: " << i + 1 << "s, " << lungs.getSummary() << std::endl;
+ *     }
+ *
+ *     // Retrieve specific final vitals
+ *     std::cout << "\n--- Simulation Results ---" << std::endl;
+ *     std::cout << "Final SpO2: " << lungs.getOxygenSaturation() << "%" << std::endl;
+ *     std::cout << "Final etCO2: " << lungs.getEndTidalCO2() << " mmHg" << std::endl;
+ *     std::cout << "Final Tidal Volume: " << lungs.getTidalVolume() << " mL" << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Lungs : public Organ {
 public:

include/MedicalLib/Pancreas.h

@@ -13,7 +13,108 @@ struct DigestiveEnzymes {
 };
 
 /**
- * @brief Represents the Pancreas, with both endocrine and exocrine functions.
+ * @brief Represents the Pancreas, simulating its dual endocrine and exocrine functions.
+ *
+ * @section bio_sec Biological Overview
+ * The pancreas is a glandular organ that sits behind the stomach. It has two primary and distinct
+ * functions, making it a "heterocrine" gland:
+ *
+ * - **Endocrine Function**: The pancreas contains clusters of cells called the islets of
+ *   Langerhans. These cells produce and secrete hormones directly into the bloodstream to regulate
+ *   blood sugar levels. The two main hormones are:
+ *   - **Insulin**: Lowers blood sugar by promoting glucose uptake by cells.
+ *   - **Glucagon**: Raises blood sugar by stimulating the liver to release stored glucose.
+ *
+ * - **Exocrine Function**: The pancreas produces powerful digestive enzymes that are secreted into
+ *   the small intestine (duodenum) to help digest food. These enzymes include:
+ *   - **Amylase**: Breaks down carbohydrates.
+ *   - **Lipase**: Breaks down fats.
+ *   - **Proteases**: Break down proteins.
+ *
+ * @section model_sec Code Simulation
+ * This `Pancreas` class models both the endocrine and exocrine roles of the organ.
+ *
+ * @subsection endocrine_model_sec Endocrine Simulation
+ * The endocrine function is simulated by tracking the secretion rates of key hormones. The `update()`
+ * method adjusts these rates based on simulated blood glucose levels (from the `Patient` object).
+ * Key outputs include:
+ * - `getInsulinSecretion()`: The rate of insulin release.
+ * - `getGlucagonSecretion()`: The rate of glucagon release.
+ *
+ * @subsection exocrine_model_sec Exocrine Simulation
+ * The exocrine function is modeled by the `releaseEnzymes()` method. When called, this method
+ * returns a `DigestiveEnzymes` struct, which contains the volume and concentration of secreted
+ * amylase and lipase, ready to be passed to the `Intestines` model.
+ *
+ * @subsection pancreas_func_sec Pancreas Function Diagram
+ * This diagram illustrates the two main functions of the pancreas.
+ *
+ * @dot
+ * digraph PancreasFunctions {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     Pancreas [shape=ellipse];
+ *
+ *     subgraph cluster_Endocrine {
+ *         label="Endocrine Function";
+ *         style=filled;
+ *         color=lightblue;
+ *         Insulin [label="Insulin"];
+ *         Glucagon [label="Glucagon"];
+ *         Bloodstream [label="Bloodstream"];
+ *         {Insulin, Glucagon} -> Bloodstream;
+ *     }
+ *
+ *     subgraph cluster_Exocrine {
+ *         label="Exocrine Function";
+ *         style=filled;
+ *         color=lightgreen;
+ *         Enzymes [label="Digestive Enzymes\n(Amylase, Lipase)"];
+ *         Duodenum [label="Small Intestine"];
+ *         Enzymes -> Duodenum;
+ *     }
+ *
+ *     Pancreas -> Insulin;
+ *     Pancreas -> Glucagon;
+ *     Pancreas -> Enzymes;
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to simulate the pancreas and access both its endocrine and
+ * exocrine function outputs.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Pancreas.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *     patient.setVital("BloodGlucose", 120.0); // Set a high blood glucose to trigger insulin
+ *
+ *     // Create a Pancreas object
+ *     Pancreas pancreas(1);
+ *
+ *     // Simulate for a short period
+ *     std::cout << "Simulating Pancreas function..." << std::endl;
+ *     pancreas.update(patient, 10.0); // Simulate 10 seconds of activity
+ *
+ *     // Check endocrine output
+ *     std::cout << "\n--- Endocrine Vitals ---" << std::endl;
+ *     std::cout << "Insulin Secretion: " << pancreas.getInsulinSecretion() << " units/hr" << std::endl;
+ *
+ *     // Check exocrine output
+ *     DigestiveEnzymes released = pancreas.releaseEnzymes(1.0);
+ *     std::cout << "\n--- Exocrine Release (1s) ---" << std::endl;
+ *     std::cout << "Volume: " << released.volume_mL << " mL" << std::endl;
+ *     std::cout << "Amylase: " << released.amylase_U_per_L << " U/L" << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Pancreas : public Organ {
 public:

include/MedicalLib/SpinalCord.h

@@ -23,7 +23,91 @@ struct SpinalTract {
 };
 
 /**
- * @brief Represents the Spinal Cord with a more detailed physiological model.
+ * @brief Represents the Spinal Cord, simulating the transmission of neural signals.
+ *
+ * @section bio_sec Biological Overview
+ * The spinal cord is a long, fragile, tube-like structure that begins at the end of the
+ * brain stem and continues down almost to the bottom of the spine. It is a vital link
+ * between the brain and the rest of the body, forming the central nervous system (CNS)
+ * along with the brain.
+ *
+ * The spinal cord has two primary functions:
+ * - **Signal Pathway**: It contains neural pathways that transmit information.
+ *   - **Ascending Tracts**: Carry sensory information (touch, pain, temperature) from the
+ *     peripheral nervous system up to the brain.
+ *   - **Descending Tracts**: Carry motor commands from the brain down to the muscles and glands.
+ * - **Reflex Coordination**: It can independently mediate simple reflexes, which are rapid,
+ *   involuntary responses to stimuli, without input from the brain.
+ *
+ * @section model_sec Code Simulation
+ * This `SpinalCord` class models the integrity and function of the major neural pathways.
+ *
+ * @subsection pathway_model_sec Pathway Model
+ * The simulation represents the major pathways as `SpinalTract` structs for the ascending
+ * (sensory) and descending (motor) signals. The integrity of these tracts is represented
+ * by the `SignalStatus` enum (`NORMAL`, `IMPAIRED`, `SEVERED`), allowing for the simulation
+ * of spinal cord injuries.
+ *
+ * Key functions to check the status include `getMotorPathwayStatus()` and `getSensoryPathwayStatus()`.
+ * A simplified `isReflexArcIntact()` function represents the status of a basic reflex.
+ *
+ * @subsection signal_flow_sec Neural Signal Flow Diagram
+ * This diagram shows the flow of motor and sensory signals between the brain, spinal cord,
+ * and the peripheral nervous system (the body).
+ *
+ * @dot
+ * digraph SignalFlow {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     Brain [shape=ellipse];
+ *     PNS [label="Peripheral Nervous System\n(Body)"];
+ *
+ *     subgraph cluster_CNS {
+ *         label="Central Nervous System";
+ *         style=filled;
+ *         color=lightblue;
+ *         SpinalCord [label="Spinal Cord"];
+ *     }
+ *
+ *     Brain -> SpinalCord [label=" Motor Commands\n(Descending Tract)"];
+ *     SpinalCord -> PNS [label=" Motor Output"];
+ *     PNS -> SpinalCord [label=" Sensory Input"];
+ *     SpinalCord -> Brain [label=" Sensory Information\n(Ascending Tract)"];
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to create a `SpinalCord` object and check its pathway status.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/SpinalCord.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a SpinalCord object
+ *     SpinalCord spinalCord(1);
+ *
+ *     // Check the initial status
+ *     std::cout << "Initial State: " << spinalCord.getSummary() << std::endl;
+ *
+ *     // In a larger simulation, an injury event might change the pathway status.
+ *     // For this example, we just check the default state.
+ *     if (spinalCord.getMotorPathwayStatus() == SignalStatus::NORMAL) {
+ *         std::cout << "Motor pathways are intact." << std::endl;
+ *     }
+ *
+ *     if (spinalCord.isReflexArcIntact()) {
+ *         std::cout << "Basic reflex arcs are functional." << std::endl;
+ *     }
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API SpinalCord : public Organ {
 public:

include/MedicalLib/Spleen.h

@@ -20,7 +20,95 @@ struct WhitePulp {
 };
 
 /**
- * @brief Represents the Spleen, involved in blood filtering and immunity.
+ * @brief Represents the Spleen, simulating its role in blood filtration and immunity.
+ *
+ * @section bio_sec Biological Overview
+ * The spleen is an organ located in the upper left part of the abdomen, and it's a key
+ * component of both the circulatory and lymphatic systems. It is not essential for life,
+ * but it performs several important functions. The spleen is composed of two primary
+ * types of tissue:
+ *
+ * - **Red Pulp**: This tissue acts as a blood filter. It removes old, malformed, or damaged
+ *   red blood cells from circulation. It also serves as a reservoir for platelets and
+ *   white blood cells, which can be released in an emergency.
+ *
+ * - **White Pulp**: This tissue is part of the immune system. It is rich in lymphocytes
+ *   (B-cells and T-cells) and macrophages. It helps identify and fight off invading
+ *   pathogens like bacteria and viruses found in the blood.
+ *
+ * @section model_sec Code Simulation
+ * This `Spleen` class models the distinct functions of the red and white pulp.
+ *
+ * @subsection pulp_model_sec Pulp-Based Functional Model
+ * The simulation separates the spleen's functions into two structs:
+ * - `RedPulp`: Models the blood filtration process, including the rate at which old red blood
+ *   cells are broken down (`getRbcBreakdownRate()`).
+ * - `WhitePulp`: Models the immune component, tracking the population of key immune cells like
+ *   lymphocytes (`getLymphocyteCount()`).
+ *
+ * The `update()` method simulates the continuous activity of both pulp types.
+ *
+ * @subsection spleen_flow_sec Spleen Function Diagram
+ * This diagram illustrates how blood is processed by the two functional parts of the spleen.
+ *
+ * @dot
+ * digraph SpleenFunctions {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     BloodIn [label="Blood Supply"];
+ *     Spleen [shape=ellipse];
+ *     BloodOut [label="Filtered Blood"];
+ *
+ *     subgraph cluster_RedPulp {
+ *         label="Red Pulp";
+ *         style=filled;
+ *         color=lightpink;
+ *         Filter [label="Filter Blood\n(Remove old RBCs)"];
+ *     }
+ *
+ *     subgraph cluster_WhitePulp {
+ *         label="White Pulp";
+ *         style=filled;
+ *         color=lightblue;
+ *         Immunity [label="Immune Surveillance\n(Lymphocytes)"];
+ *     }
+ *
+ *     BloodIn -> Spleen;
+ *     Spleen -> Filter;
+ *     Spleen -> Immunity;
+ *     {Filter, Immunity} -> BloodOut;
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to create a `Spleen` object and get a summary of its state.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Spleen.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Spleen object
+ *     Spleen spleen(1);
+ *
+ *     // Simulate for a short period
+ *     std::cout << "Simulating Spleen function..." << std::endl;
+ *     spleen.update(patient, 10.0); // Simulate 10 seconds of activity
+ *     std::cout << spleen.getSummary() << std::endl;
+ *
+ *     // Retrieve specific data
+ *     std::cout << "\n--- Spleen Vitals ---" << std::endl;
+ *     std::cout << "RBC Breakdown Rate: " << spleen.getRbcBreakdownRate() << std::endl;
+ *     std::cout << "Lymphocyte Count: " << spleen.getLymphocyteCount() << " million" << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Spleen : public Organ {
 public:

include/MedicalLib/Stomach.h

@@ -23,7 +23,85 @@ struct Chyme {
 };
 
 /**
- * @brief Represents the Stomach with a more detailed physiological model.
+ * @brief Represents the Stomach, simulating the initial stages of digestion.
+ *
+ * @section bio_sec Biological Overview
+ * The stomach is a muscular, J-shaped organ in the upper abdomen. It is a key part of the
+ * digestive system. Its primary functions are:
+ * - **Storage**: It acts as a temporary reservoir for food coming from the esophagus, allowing
+ *   for a large meal to be consumed at once.
+ * - **Digestion**: It secretes strong gastric juices, primarily hydrochloric acid and the enzyme
+ *   pepsin, which begin the process of breaking down proteins. The stomach's muscular walls
+ *   (rugae) contract to mix the food with these juices.
+ * - **Controlled Release**: The stomach turns the food into a semi-liquid mixture called **chyme**.
+ *   It then slowly releases this chyme into the small intestine (duodenum) for further
+ *   digestion and nutrient absorption.
+ *
+ * The digestive process involves several states, from being empty, to filling, actively
+ * digesting, and finally emptying its contents.
+ *
+ * @section model_sec Code Simulation
+ * This `Stomach` class models the digestive cycle of the stomach.
+ *
+ * @subsection state_model_sec State-Based Digestive Model
+ * The simulation is managed as a state machine, governed by the `GastricState` enum. The stomach
+ * transitions through these states based on its contents and time:
+ * - `EMPTY`: No contents.
+ * - `FILLING`: Food is being added (via `addSubstance()`).
+ * - `DIGESTING`: Contents are being mixed and broken down, and pH is lowered.
+ * - `EMPTYING`: Chyme is being passed to the intestines.
+ *
+ * The contents themselves are modeled by the `Chyme` struct, which tracks volume and acidity.
+ * The `update()` method drives the state transitions and simulates the secretion of gastric
+ * juices and the emptying process.
+ *
+ * @subsection gastric_state_diagram_sec Gastric State Diagram
+ * The following diagram illustrates the transitions between the stomach's digestive states.
+ *
+ * @dot
+ * digraph GastricStates {
+ *     rankdir="TB";
+ *     node [shape=box, style=rounded];
+ *
+ *     EMPTY -> FILLING [label="addSubstance()"];
+ *     FILLING -> DIGESTING [label="update()"];
+ *     DIGESTING -> EMPTYING [label="update() over time"];
+ *     EMPTYING -> EMPTY [label="volume = 0"];
+ * }
+ * @enddot
+ *
+ * @section usage_sec Example Usage
+ * The following C++ code shows how to add food to the stomach and observe the resulting
+ * changes in its state and volume.
+ *
+ * @code{.cpp}
+ * #include <iostream>
+ * #include "MedicalLib/Stomach.h"
+ * #include "MedicalLib/Patient.h"
+ *
+ * int main() {
+ *     // A patient object is needed for the update function
+ *     Patient patient;
+ *
+ *     // Create a Stomach object
+ *     Stomach stomach(1);
+ *     std::cout << "Initial State: " << stomach.getSummary() << std::endl;
+ *
+ *     // Add a meal
+ *     std::cout << "\nEating a 500mL meal..." << std::endl;
+ *     stomach.addSubstance(500.0);
+ *     std::cout << "State after eating: " << stomach.getSummary() << std::endl;
+ *
+ *     // Simulate digestion over time
+ *     std::cout << "\nSimulating digestion for 30 minutes..." << std::endl;
+ *     for (int i = 0; i < 30; ++i) {
+ *         stomach.update(patient, 60.0); // Simulate 1 minute
+ *     }
+ *     std::cout << "State after 30 mins: " << stomach.getSummary() << std::endl;
+ *
+ *     return 0;
+ * }
+ * @endcode
  */
 class MEDICAL_LIB_API Stomach : public Organ {
 public: