From bfa583d574f258b4f7373aca4fa37aff6586e1a8 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 18 Aug 2025 09:56:29 +0000 Subject: [PATCH] feat: Add Doxygen documentation and Gitea workflow This commit introduces Doxygen for documentation generation and a Gitea workflow for continuous integration. - Adds a `Doxyfile` to configure Doxygen to build a documentation website with diagrams. - Updates `AGENTS.md` to require Doxygen-compatible comments for all code. - Adds Doxygen comments to existing C++ source files to comply with the new standard. - Creates a Gitea workflow (`.gitea/workflows/build.yml`) that: - Builds the project on every push. - Generates Doxygen documentation. - Uploads the compiled library and the documentation website as artifacts. --- .gitea/workflows/build.yml | 33 +++++++++++++++++++++++++ AGENTS.md | 23 ++++++++++++++++++ Doxyfile | 49 ++++++++++++++++++++++++++++++++++++++ src/MedicalLib.cpp | 7 ++++++ src/Patient.cpp | 17 ++++++++++++- 5 files changed, 128 insertions(+), 1 deletion(-) create mode 100644 .gitea/workflows/build.yml create mode 100644 Doxyfile diff --git a/.gitea/workflows/build.yml b/.gitea/workflows/build.yml new file mode 100644 index 0000000..76bdfa4 --- /dev/null +++ b/.gitea/workflows/build.yml @@ -0,0 +1,33 @@ +name: Build and Test + +on: [push] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Install dependencies + run: | + sudo apt-get update + sudo apt-get install -y g++ cmake doxygen graphviz + + - name: Build + run: ./build.sh + + - name: Generate Documentation + run: doxygen Doxyfile + + - name: Upload Library Artifact + uses: actions/upload-artifact@v4 + with: + name: medical-lib + path: build/lib + + - name: Upload Documentation Artifact + uses: actions/upload-artifact@v4 + with: + name: documentation + path: docs/html diff --git a/AGENTS.md b/AGENTS.md index 0be2e46..d63a9b8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -31,6 +31,29 @@ To build the project, use the provided build scripts: The compiled library will be placed in `build/lib`, and the example executable will be in `build/examples/`. +## Coding Standards + +### Doxygen Documentation + +All functions, classes, structs, enums, and public member variables must be documented using Doxygen-compatible comments. This ensures that the code is easy to understand and that high-quality documentation can be automatically generated. + +- Use `/** ... */` for multi-line comments. +- Use `///` for single-line comments. +- Use `@brief` to provide a short description. +- Use `@param` to document function parameters. +- Use `@return` to describe the return value. + +Example: +```cpp +/** + * @brief Calculates the Body Mass Index (BMI). + * @param weight_kg The weight in kilograms. + * @param height_m The height in meters. + * @return The calculated BMI. + */ +MEDICAL_LIB_API double calculateBMI(double weight_kg, double height_m); +``` + ## Integration with Unreal Engine To use this library in an Unreal Engine plugin: diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..c655027 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,49 @@ +# Doxyfile 1.9.1 + +# Project +PROJECT_NAME = "MedicalLib" +PROJECT_NUMBER = 1.0 +PROJECT_BRIEF = "A C++ library for medical simulations" +OUTPUT_DIRECTORY = "docs" +CREATE_SUBDIRS = YES +OUTPUT_LANGUAGE = English +BRIEF_MEMBER_DESC = YES +REPEAT_BRIEF = YES + +# Sources +INPUT = ./include ./src +FILE_PATTERNS = *.h *.cpp +RECURSIVE = YES +EXCLUDE_PATTERNS = +EXCLUDE_SYMBOLS = + +# HTML +GENERATE_HTML = YES +HTML_OUTPUT = html +HTML_FILE_EXTENSION = .html +HTML_HEADER = +HTML_FOOTER = +HTML_STYLESHEET = +HTML_COLORSTYLE_HUE = 220 +HTML_COLORSTYLE_SAT = 100 +HTML_COLORSTYLE_GAMMA = 80 + +# Diagrams +HAVE_DOT = YES +DOT_TOOL_PATH = +DOTFILE_DIRS = +UML_LOOK = YES +UML_LIMIT_NUM_FIELDS = 10 +TEMPLATE_RELATIONS = YES +CALL_GRAPH = YES +CALLER_GRAPH = YES +GRAPHICAL_HIERARCHY = YES +DIRECTORY_GRAPH = YES +DOT_IMAGE_FORMAT = png +INTERACTIVE_SVG = NO +DOT_GRAPH_MAX_NODES = 50 +MAX_DOT_GRAPH_DEPTH = 0 +DOT_TRANSPARENT = NO +DOT_MULTI_TARGETS = YES +GENERATE_LEGEND = YES +DOT_CLEANUP = YES diff --git a/src/MedicalLib.cpp b/src/MedicalLib.cpp index 8adf398..38c8504 100644 --- a/src/MedicalLib.cpp +++ b/src/MedicalLib.cpp @@ -1,6 +1,13 @@ #include "MedicalLib/MedicalLib.h" #include +/** + * @brief Calculates the Body Mass Index (BMI). + * @param weight_kg The weight in kilograms. + * @param height_m The height in meters. + * @return The calculated BMI. + * @throws std::invalid_argument if height or weight are non-positive. + */ double calculateBMI(double weight_kg, double height_m) { if (height_m <= 0) { throw std::invalid_argument("Height must be positive."); diff --git a/src/Patient.cpp b/src/Patient.cpp index 95d0ace..427a3b0 100644 --- a/src/Patient.cpp +++ b/src/Patient.cpp @@ -2,7 +2,11 @@ #include #include // For std::clamp -// Helper function to generate random fluctuations +/** + * @brief Helper function to generate random fluctuations from a normal distribution. + * @param stddev The standard deviation of the distribution. + * @return A random value. + */ double getFluctuation(double stddev) { static std::random_device rd; static std::mt19937 gen(rd()); @@ -10,6 +14,11 @@ double getFluctuation(double stddev) { return d(gen); } +/** + * @brief Initializes a new patient with baseline vital signs. + * @param patientId The ID for the new patient. + * @return A Patient struct with default healthy values. + */ Patient initializePatient(int patientId) { Patient patient; patient.patientId = patientId; @@ -22,6 +31,12 @@ Patient initializePatient(int patientId) { return patient; } +/** + * @brief Updates the patient's vital signs based on the time elapsed. + * This function simulates minor, random fluctuations around a healthy baseline. + * @param patient The patient to update. + * @param deltaTime_s The time elapsed in seconds. + */ void updatePatient(Patient& patient, double deltaTime_s) { // Baseline healthy values const double baseline_hr = 75.0;