Add Doxygen config, submodule, and API docs

Add Doxygen/Read the Docs plumbing and document the public API.

- Add .readthedocs.yaml and docs/Doxyfile to configure Read the Docs and Doxygen.
- Add third-party/doxyconfig as a git submodule and update .gitmodules and .gitignore.
- Wire docs submodule into CMake (top-level BUILD_DOCS option) so docs can be built when top-level.
- Document public headers: add Doxygen-style comments and API surface annotations to include/libvirtualhid/*.hpp (libvirtualhid.hpp, profiles.hpp, report.hpp, runtime.hpp, types.hpp).
- Update README to mention the new docs directory and the doxyconfig submodule.

These changes enable building hosted documentation (Read the Docs) and provide inline API documentation for consumers of the public headers.

Author: ReenigneArcher

.gitignore

@@ -4,3 +4,9 @@
 # CMake
 build/
 cmake-build-*/
+
+# Local temp directories
+.tmp/
+
+# doxyconfig
+docs/doxyconfig*

.gitmodules

@@ -1,3 +1,7 @@
+[submodule "third-party/doxyconfig"]
+	path = third-party/doxyconfig
+	url = https://github.com/LizardByte/doxyconfig.git
+	branch = master
 [submodule "third-party/googletest"]
 	path = third-party/googletest
 	url = https://github.com/google/googletest.git

.readthedocs.yaml

@@ -0,0 +1,30 @@
+---
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "miniconda-latest"
+  commands:
+    - |
+      if [ -f readthedocs_build.sh ]; then
+        doxyconfig_dir="."
+      else
+        doxyconfig_dir="./third-party/doxyconfig"
+      fi
+      chmod +x "${doxyconfig_dir}/readthedocs_build.sh"
+      export DOXYCONFIG_DIR="${doxyconfig_dir}"
+      "${doxyconfig_dir}/readthedocs_build.sh"
+
+# using conda, we can get newer doxygen and graphviz than ubuntu provide
+# https://github.com/readthedocs/readthedocs.org/issues/8151#issuecomment-890359661
+conda:
+  environment: third-party/doxyconfig/environment.yml
+
+submodules:
+  include: all
+  recursive: true

CMakeLists.txt

@@ -27,7 +27,7 @@ list(APPEND CMAKE_MODULE_PATH "${CMAKE_CURRENT_SOURCE_DIR}/cmake")
 #
 # Project optional configuration
 #
-option(BUILD_DOCS "Build documentation" OFF)
+option(BUILD_DOCS "Build documentation" ${LIBVIRTUALHID_IS_TOP_LEVEL})
 option(BUILD_TESTS "Build tests" ${LIBVIRTUALHID_IS_TOP_LEVEL})
 option(BUILD_EXAMPLES "Build examples" ${LIBVIRTUALHID_IS_TOP_LEVEL})
 
@@ -64,6 +64,10 @@ add_subdirectory(src)
 # Examples, tests, and docs are top-level only
 #
 if(CMAKE_PROJECT_NAME STREQUAL PROJECT_NAME)
+    if(BUILD_DOCS)
+        add_subdirectory(third-party/doxyconfig docs)
+    endif()
+
     if(BUILD_EXAMPLES)
         add_subdirectory(examples)
     endif()

README.md

@@ -191,6 +191,8 @@ consumers:
 - Put all submodules under `third-party`.
 - Add GoogleTest as a submodule at `third-party/googletest`; do not download it
   during configure.
+- Add the LizardByte Doxygen configuration as a submodule at
+  `third-party/doxyconfig` and use it for local docs and Read the Docs builds.
 - Expose `libvirtualhid::libvirtualhid` as the main CMake target.
 - Keep the public headers under `include/libvirtualhid` and the implementation
   split into shared core code plus platform-specific backends.
@@ -215,6 +217,8 @@ profiles/                     Built-in gamepad profiles
 examples/                     Minimal consumers and platform smoke tests
 tests/                        Unit and integration tests
 cmake/                        Package config and helper modules
+docs/                         Project Doxygen configuration
+third-party/doxyconfig/       LizardByte Doxygen configuration submodule
 third-party/googletest/       GoogleTest submodule
 ```
 
@@ -228,6 +232,8 @@ third-party/googletest/       GoogleTest submodule
 - Add a fake in-memory backend so API tests can run on every platform.
 - Add GoogleTest as a submodule under `third-party/googletest` and wire tests
   using the same top-level-only pattern as `tray` and `libdisplaydevice`.
+- Add Doxygen documentation wiring with `third-party/doxyconfig`, a project
+  `docs/Doxyfile`, and Read the Docs configuration.
 - Add CI using the `libdisplaydevice` workflow pattern for Linux GCC, Linux
   Clang, macOS, Windows MinGW/UCRT64, and Windows MSVC configure/build/test
   coverage.

docs/Doxyfile

@@ -0,0 +1,39 @@
+# This file describes the settings to be used by the documentation system
+# doxygen (www.doxygen.org) for a project.
+#
+# All text after a double hash (##) is considered a comment and is placed in
+# front of the TAG it is preceding.
+#
+# All text after a single hash (#) is considered a comment and will be ignored.
+# The format is:
+# TAG = value [value, ...]
+# For lists, items can also be appended using:
+# TAG += value [value, ...]
+# Values that contain spaces should be placed between quotes (\" \").
+#
+# Note:
+#
+# Use doxygen to compare the used configuration file with the template
+# configuration file:
+# doxygen -x [configFile]
+# Use doxygen to compare the used configuration file with the template
+# configuration file without replacing the environment variables or CMake type
+# replacement variables:
+# doxygen -x_noenv [configFile]
+
+# project metadata
+DOCSET_BUNDLE_ID = dev.lizardbyte.libvirtualhid
+DOCSET_PUBLISHER_ID = dev.lizardbyte.libvirtualhid.documentation
+PROJECT_BRIEF = "Cross-platform C++ library for virtual HID devices."
+PROJECT_NAME = libvirtualhid
+
+# project specific settings
+DOT_GRAPH_MAX_NODES = 50
+INCLUDE_PATH =
+WARN_IF_UNDOCUMENTED = YES
+
+# files and directories to process
+USE_MDFILE_AS_MAINPAGE = ../README.md
+INPUT = ../README.md \
+        ../third-party/doxyconfig/docs/source_code.md \
+        ../include

include/libvirtualhid/libvirtualhid.hpp

@@ -1,5 +1,10 @@
 #pragma once
 
+/**
+ * @file libvirtualhid/libvirtualhid.hpp
+ * @brief Aggregate include for the libvirtualhid public C++ API.
+ */
+
 #include <libvirtualhid/profiles.hpp>
 #include <libvirtualhid/report.hpp>
 #include <libvirtualhid/runtime.hpp>

include/libvirtualhid/profiles.hpp

@@ -7,14 +7,61 @@
 
 namespace lvh::profiles {
 
+/**
+ * @brief Create the generic HID gamepad profile.
+ *
+ * @return Generic gamepad device profile.
+ */
 DeviceProfile generic_gamepad();
+
+/**
+ * @brief Create the Xbox 360-compatible gamepad profile.
+ *
+ * @return Xbox 360-compatible device profile.
+ */
 DeviceProfile xbox_360();
+
+/**
+ * @brief Create the Xbox One-compatible gamepad profile.
+ *
+ * @return Xbox One-compatible device profile.
+ */
 DeviceProfile xbox_one();
+
+/**
+ * @brief Create the Xbox Series-compatible gamepad profile.
+ *
+ * @return Xbox Series-compatible device profile.
+ */
 DeviceProfile xbox_series();
+
+/**
+ * @brief Create the PlayStation DualSense-compatible gamepad profile.
+ *
+ * @return DualSense-compatible device profile.
+ */
 DeviceProfile dualsense();
+
+/**
+ * @brief Create the Nintendo Switch Pro-compatible gamepad profile.
+ *
+ * @return Switch Pro-compatible device profile.
+ */
 DeviceProfile switch_pro();
 
+/**
+ * @brief Look up a built-in gamepad profile by kind.
+ *
+ * @param kind Built-in gamepad profile kind.
+ * @return Matching profile, or `std::nullopt` when the kind is unknown.
+ */
 std::optional<DeviceProfile> gamepad_profile(GamepadProfileKind kind);
+
+/**
+ * @brief Get every built-in gamepad profile.
+ *
+ * @return Built-in gamepad profiles.
+ */
 std::vector<DeviceProfile> built_in_gamepad_profiles();
 
 }  // namespace lvh::profiles

include/libvirtualhid/report.hpp

@@ -7,12 +7,61 @@
 
 namespace lvh::reports {
 
+/**
+ * @brief Clamp a stick axis value to the normalized range.
+ *
+ * @param value Axis value.
+ * @return Clamped axis value in the inclusive range `[-1.0, 1.0]`.
+ */
 float clamp_axis(float value);
+
+/**
+ * @brief Clamp a trigger value to the normalized range.
+ *
+ * @param value Trigger value.
+ * @return Clamped trigger value in the inclusive range `[0.0, 1.0]`.
+ */
 float clamp_trigger(float value);
+
+/**
+ * @brief Convert a normalized axis value to a signed HID axis value.
+ *
+ * @param value Axis value in the inclusive range `[-1.0, 1.0]`.
+ * @return Signed 16-bit HID axis value.
+ */
 std::int16_t normalize_axis(float value);
+
+/**
+ * @brief Convert a normalized trigger value to an unsigned HID trigger value.
+ *
+ * @param value Trigger value in the inclusive range `[0.0, 1.0]`.
+ * @return Unsigned 8-bit HID trigger value.
+ */
 std::uint8_t normalize_trigger(float value);
+
+/**
+ * @brief Normalize all scalar fields in a gamepad state.
+ *
+ * @param state Gamepad state to normalize.
+ * @return Normalized gamepad state.
+ */
 GamepadState normalize_state(const GamepadState& state);
+
+/**
+ * @brief Convert directional pad buttons to a HID hat switch value.
+ *
+ * @param buttons Button set containing directional pad state.
+ * @return HID hat switch value, or `8` for neutral.
+ */
 std::uint8_t hat_from_buttons(const ButtonSet& buttons);
+
+/**
+ * @brief Pack a gamepad state into the profile's common input report format.
+ *
+ * @param profile Device profile used for report identity and size.
+ * @param state Gamepad state to pack.
+ * @return Packed input report bytes.
+ */
 std::vector<std::uint8_t> pack_input_report(const DeviceProfile& profile, const GamepadState& state);
 
 }  // namespace lvh::reports