Merge pull request #19 from Jgocunha/feature/doxygen

docs: add Doxygen API reference and fix wiki/README gaps

Author: Jgocunha

.github/workflows/docs.yml

@@ -0,0 +1,53 @@
+name: Documentation
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install -y doxygen graphviz
+
+      - name: Generate docs
+        run: doxygen Doxyfile
+        working-directory: imgui-platform-kit
+
+      - name: Copy README images
+        run: |
+          mkdir -p imgui-platform-kit/docs/html/imgui-platform-kit/resources/images
+          cp imgui-platform-kit/resources/images/*.png imgui-platform-kit/docs/html/imgui-platform-kit/resources/images/
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: imgui-platform-kit/docs/html
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -6,6 +6,9 @@
 
 install/
 build/
+
+# Generated Doxygen output
+imgui-platform-kit/docs/
 # Prerequisites
 *.d
 

README.md

@@ -1,5 +1,5 @@
 
-<img src="./imgui-platform-kit/resources/images/logo-bg.png" alt="logo" length="400" width="400">
+<img src="./imgui-platform-kit/resources/images/logo-bg.png" alt="logo" height="400" width="400">
 
 
 imgui-platform-kit - Cross-platform toolkit for Dear ImGui.
@@ -10,6 +10,7 @@ imgui-platform-kit - Cross-platform toolkit for Dear ImGui.
 [![macOS](https://img.shields.io/github/actions/workflow/status/Jgocunha/imgui-platform-kit/macos.yml?branch=main&style=flat-square&logo=apple&logoColor=white&label=macOS)](https://github.com/Jgocunha/imgui-platform-kit/actions/workflows/macos.yml)
 [![Coverage](https://img.shields.io/codecov/c/github/Jgocunha/imgui-platform-kit?style=flat-square&logo=codecov&logoColor=white)](https://codecov.io/gh/Jgocunha/imgui-platform-kit)
 [![Wiki](https://img.shields.io/badge/docs-wiki-blue?style=flat-square&logo=github&logoColor=white)](https://github.com/Jgocunha/imgui-platform-kit/wiki)
+[![API Reference](https://img.shields.io/badge/docs-API%20reference-blue?style=flat-square&logo=doxygen&logoColor=white)](https://jgocunha.github.io/imgui-platform-kit/)
 
 [![C++20](https://img.shields.io/badge/C%2B%2B-20-00599C?style=flat-square&logo=cplusplus&logoColor=white)](https://en.cppreference.com/w/cpp/20)
 [![CMake](https://img.shields.io/badge/CMake-3.15%2B-064F8C?style=flat-square&logo=cmake&logoColor=white)](https://cmake.org)
@@ -104,9 +105,9 @@ target_link_libraries(MyAwesomeApp PRIVATE imgui-platform-kit)
 
 1. **Define Your Window Class**:
  ```cpp
- #include "base_window.h"
+ #include "user_interface_window.h"
 
- class MyCustomWindow : public BaseWindow 
+ class MyCustomWindow : public imgui_kit::UserInterfaceWindow 
  {
  public:
      MyCustomWindow();

imgui-platform-kit/Doxyfile

@@ -0,0 +1,60 @@
+# Doxyfile for imgui-platform-kit
+# Only settings that differ from the Doxygen defaults are listed.
+
+#---------------------------------------------------------------------------
+# Project
+#---------------------------------------------------------------------------
+PROJECT_NAME           = "imgui-platform-kit"
+PROJECT_NUMBER         = 2.0.0
+PROJECT_BRIEF          = "Cross-platform Dear ImGui application framework"
+OUTPUT_DIRECTORY       = docs
+
+#---------------------------------------------------------------------------
+# Input
+#---------------------------------------------------------------------------
+INPUT                  = include \
+                         ../README.md
+RECURSIVE              = YES
+EXCLUDE_PATTERNS       = */stb_image.h
+USE_MDFILE_AS_MAINPAGE = ../README.md
+IMAGE_PATH             = resources/images
+
+#---------------------------------------------------------------------------
+# Extraction
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_STATIC         = YES
+JAVADOC_AUTOBRIEF      = YES
+BUILTIN_STL_SUPPORT    = YES
+
+#---------------------------------------------------------------------------
+# Preprocessing
+# _WIN32 is predefined so that a single canonical UserInterface (the
+# Win32/DX12 backend) is documented; the GLFW backends expose an identical
+# public API. IM_FMTARGS is an ImGui format-checking macro with no
+# documentation value.
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+PREDEFINED             = _WIN32 \
+                         "IM_FMTARGS(x)="
+
+#---------------------------------------------------------------------------
+# Output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+GENERATE_LATEX         = NO
+GENERATE_TREEVIEW      = YES
+
+#---------------------------------------------------------------------------
+# Warnings
+#---------------------------------------------------------------------------
+QUIET                  = YES
+WARN_IF_UNDOCUMENTED   = YES
+
+#---------------------------------------------------------------------------
+# Diagrams (requires graphviz)
+#---------------------------------------------------------------------------
+HAVE_DOT               = YES
+DOT_IMAGE_FORMAT       = svg

imgui-platform-kit/include/colour_palette.h

@@ -1,11 +1,24 @@
 #pragma once
 
+/**
+ * @file colour_palette.h
+ * @brief Named colour constants for use with ImGui (e.g. LogWindow::addLog()).
+ */
+
 #include "imgui.h"
 
 namespace imgui_kit
 {
+	/**
+	 * @brief Named @c constexpr ImVec4 colour constants (RGBA, 0.0-1.0).
+	 */
 	namespace colours
 	{
+        /**
+         * @defgroup colours_basic Basic colours
+         * @brief Primary and secondary colours.
+         * @{
+         */
         // Basic Colors
         constexpr ImVec4 White = ImVec4(1.00f, 1.00f, 1.00f, 1.00f);
         constexpr ImVec4 Black = ImVec4(0.00f, 0.00f, 0.00f, 1.00f);
@@ -17,7 +30,13 @@ namespace imgui_kit
         constexpr ImVec4 Purple = ImVec4(0.50f, 0.00f, 0.50f, 1.00f);
         constexpr ImVec4 Cyan = ImVec4(0.00f, 1.00f, 1.00f, 1.00f);
         constexpr ImVec4 Magenta = ImVec4(1.00f, 0.00f, 1.00f, 1.00f);
+        /** @} */
 
+        /**
+         * @defgroup colours_extended Extended palette
+         * @brief Additional named colours.
+         * @{
+         */
         // Extended Palette
         constexpr ImVec4 Coral = ImVec4(1.00f, 0.50f, 0.31f, 1.00f);
         constexpr ImVec4 Violet = ImVec4(0.93f, 0.51f, 0.93f, 1.00f);
@@ -31,21 +50,39 @@ namespace imgui_kit
         constexpr ImVec4 Navy = ImVec4(0.00f, 0.00f, 0.50f, 1.00f);
         constexpr ImVec4 Mint = ImVec4(0.74f, 1.00f, 0.98f, 1.00f);
         constexpr ImVec4 Peach = ImVec4(1.00f, 0.89f, 0.71f, 1.00f);
+        /** @} */
 
+        /**
+         * @defgroup colours_grayscale Grayscales
+         * @brief Shades of grey.
+         * @{
+         */
         // Grayscales
         constexpr ImVec4 DarkGray = ImVec4(0.20f, 0.20f, 0.20f, 1.00f);
         constexpr ImVec4 Gray = ImVec4(0.50f, 0.50f, 0.50f, 1.00f);
         constexpr ImVec4 LightGray = ImVec4(0.75f, 0.75f, 0.75f, 1.00f);
         constexpr ImVec4 Silver = ImVec4(0.75f, 0.75f, 0.80f, 1.00f);
+        /** @} */
 
+        /**
+         * @defgroup colours_pastel Pastel colours
+         * @brief Soft, low-saturation colours.
+         * @{
+         */
         // Pastel Colors
         constexpr ImVec4 PastelPink = ImVec4(1.00f, 0.82f, 0.86f, 1.00f);
         constexpr ImVec4 PastelGreen = ImVec4(0.47f, 0.87f, 0.47f, 1.00f);
         constexpr ImVec4 PastelBlue = ImVec4(0.68f, 0.85f, 0.90f, 1.00f);
         constexpr ImVec4 PastelYellow = ImVec4(0.99f, 0.99f, 0.59f, 1.00f);
         constexpr ImVec4 PastelOrange = ImVec4(1.00f, 0.70f, 0.28f, 1.00f);
         constexpr ImVec4 PastelViolet = ImVec4(0.80f, 0.60f, 0.80f, 1.00f);
+        /** @} */
 
+        /**
+         * @defgroup colours_dark Dark colours
+         * @brief Darkened variants of the basic colours.
+         * @{
+         */
         // Dark Colors
         constexpr ImVec4 DarkRed = ImVec4(0.55f, 0.00f, 0.00f, 1.00f);
         constexpr ImVec4 DarkGreen = ImVec4(0.00f, 0.39f, 0.00f, 1.00f);
@@ -55,6 +92,7 @@ namespace imgui_kit
         constexpr ImVec4 DarkCyan = ImVec4(0.00f, 0.55f, 0.55f, 1.00f);
         constexpr ImVec4 DarkMagenta = ImVec4(0.55f, 0.00f, 0.55f, 1.00f);
         constexpr ImVec4 DarkOrange = ImVec4(0.55f, 0.27f, 0.07f, 1.00f);
+        /** @} */
 	}
-    
-}
+
+}

imgui-platform-kit/include/linux/glfw_opengl3_user_interface.h

@@ -1,6 +1,15 @@
 
 #pragma once
 
+/**
+ * @file glfw_opengl3_user_interface.h
+ * @brief Linux backend of imgui_kit::UserInterface (GLFW + OpenGL 3).
+ *
+ * Include the platform-independent user_interface.h instead of this header;
+ * it selects the right backend automatically. The public API is identical to
+ * the documented Windows variant.
+ */
+
 #if defined(__linux__)
 
 #include "imgui.h"
@@ -45,6 +54,10 @@ namespace ImNodeEditor = ax::NodeEditor;
 
 namespace imgui_kit
 {
+    /**
+     * @brief OpenGL texture holding the background image and its parameters.
+     * Managed internally by UserInterface.
+     */
     struct GLFWbackgroundImageTexture
     {
         GLuint texture;
@@ -60,6 +73,12 @@ namespace imgui_kit
         {}
     };
 
+    /**
+     * @brief Main application object (Linux GLFW + OpenGL 3 backend).
+     *
+     * Same public API as the documented Windows variant: initialize(),
+     * render(), shutdown(), isShutdownRequested() and addWindow().
+     */
     class UserInterface
     {
     private:

imgui-platform-kit/include/log_window.h

@@ -1,6 +1,11 @@
 
 #pragma once
 
+/**
+ * @file log_window.h
+ * @brief Built-in log window with colour-coded entries, filtering and auto-scroll.
+ */
+
 #include <vector>
 #include <string>
 #include <cstdarg>
@@ -10,12 +15,23 @@
 
 namespace imgui_kit
 {
+    /// A single log line: message text and its display colour.
     struct LogEntry
 	{
-        std::string message;
-        ImVec4 color;
+        std::string message; ///< Text of the log line.
+        ImVec4 color;        ///< Colour used to render the line (see imgui_kit::colours).
     };
 
+    /**
+     * @brief Built-in window that displays colour-coded log messages.
+     *
+     * The log storage is static and shared: call addLog() from anywhere in
+     * the application, before or after a LogWindow instance exists. The
+     * window provides a text filter and an auto-scroll option.
+     *
+     * Register it with UserInterface::addWindow<LogWindow>(), or embed the
+     * log UI inside your own window with renderContent().
+     */
     class LogWindow final : public UserInterfaceWindow
 	{
     private:
@@ -26,11 +42,28 @@ namespace imgui_kit
 
     public:
         LogWindow();
+        /**
+         * @brief Appends a printf-style formatted message to the log.
+         * @param color Colour used to render the message (see imgui_kit::colours).
+         * @param fmt printf-style format string.
+         * @param ... Format arguments.
+         */
         static void addLog(const ImVec4& color, const char* fmt, ...) IM_FMTARGS(2);
+        /// Renders the log window. Called once per frame by the UserInterface.
         void render() override { draw(); }
+        /// Returns true while the log window is open and being rendered.
         static bool isActive() { return isWindowActive; }
+        /// Returns the number of stored log entries.
         static size_t getLogCount() { return logs.size(); }
+        /// Removes all stored log entries.
         static void clearLogs() { logs.clear(); }
+        /**
+         * @brief Renders the log contents (toolbar, filter and entries) into
+         * the current ImGui window.
+         *
+         * Use this to embed the log UI inside a custom window instead of
+         * registering a standalone LogWindow.
+         */
         static void renderContent();
         ~LogWindow() override = default;
     private:

imgui-platform-kit/include/macos/glfw_opengl3_user_interface.h

@@ -1,6 +1,15 @@
 
 #pragma once
 
+/**
+ * @file glfw_opengl3_user_interface.h
+ * @brief macOS backend of imgui_kit::UserInterface (GLFW + OpenGL 3).
+ *
+ * Include the platform-independent user_interface.h instead of this header;
+ * it selects the right backend automatically. The public API is identical to
+ * the documented Windows variant.
+ */
+
 #if defined(__APPLE__)
 
 #include "imgui.h"
@@ -30,6 +39,10 @@ namespace ImNodeEditor = ax::NodeEditor;
 
 namespace imgui_kit
 {
+    /**
+     * @brief OpenGL texture holding the background image and its parameters.
+     * Managed internally by UserInterface.
+     */
     struct GLFWbackgroundImageTexture
     {
         GLuint texture;
@@ -45,6 +58,14 @@ namespace imgui_kit
         {}
     };
 
+    /**
+     * @brief Main application object (macOS GLFW + OpenGL 3 backend).
+     *
+     * Same public API as the documented Windows variant: initialize(),
+     * render(), shutdown(), isShutdownRequested() and addWindow().
+     * @note Setting a window icon is a no-op on macOS (GLFW limitation);
+     * the application icon comes from the app bundle instead.
+     */
     class UserInterface
     {
     private: