Automate doxygen builds (#521)

- updated the doxyfile using doxygen -u
- include hidtest/test.c as a doc'd example
- use a brief doxygen/main_page.md file as the generated site's main page
- strip absolute paths from doxygen output (which now displays as relative paths to repo root)
- add CI to build the docs and save as a CI artifact and rewrite the contents of the gh-pages branch for deployment (for master builds)
- add some missing docstrings and excluded undocumented "helper macros" to satisfy warnings output in doxygen's build log

.github/workflows/docs.yaml

@@ -13,3 +13,46 @@ jobs:
 
       - name: Install Doxygen static libclang deps
         run: sudo apt-get install libclang1-12 libclang-cpp12
+
+      - name: Install Doxygen from SF binary archives
+        env:
+          DOXYGEN_VERSION: '1.9.6'
+        run: |
+          mkdir .doxygen && cd .doxygen
+          curl -L https://sourceforge.net/projects/doxygen/files/rel-$DOXYGEN_VERSION/doxygen-$DOXYGEN_VERSION.linux.bin.tar.gz > doxygen.tar.gz
+          gunzip doxygen.tar.gz
+          tar xf doxygen.tar
+          cd doxygen-$DOXYGEN_VERSION
+          sudo make install
+
+      - uses: actions/checkout@v3
+
+      - run: doxygen
+        working-directory: doxygen
+
+      - name: Save doxygen docs as artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: HIDAPI_doxygen_docs
+          path: ${{ github.workspace }}/doxygen/html
+
+  deploy-docs:
+    runs-on: ubuntu-latest
+    needs: [build]
+    if: github.ref_type == 'branch' && github.ref_name == 'master'
+    concurrency:
+      group: "github-pages-deploy"
+      cancel-in-progress: true
+    steps:
+      - name: downlod artifact
+        uses: actions/download-artifact@v3
+        with:
+          name: HIDAPI_doxygen_docs
+          path: docs
+
+      - name: upload to github pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          force_orphan: true

.gitignore

@@ -27,3 +27,6 @@ libtool
 
 # Qt Creator
 CMakeLists.txt.user
+
+# doxgen output
+doxygen/html/

doxygen/main_page.md

@@ -0,0 +1,13 @@
+# HIDAPI Doxygen output
+
+This site is dedicated to hosting an [API reference for the HIDAPI library](#API).
+
+For general information, see the [source repository](https://github.com/libusb/hidapi#readme).
+
+There are also build instructions hosted on github:
+
+- [Building from source](https://github.com/libusb/hidapi/blob/master/BUILD.md)
+- [Using CMake](https://github.com/libusb/hidapi/blob/master/BUILD.cmake.md)
+- [Using Autotools (deprecated)](https://github.com/libusb/hidapi/blob/master/BUILD.autotools.md)
+
+\example test.c contains a basic example usage of the HIDAPI library.

hidapi/hidapi.h

@@ -70,7 +70,9 @@
 	This macro was added in version 0.12.0.
 
 	Convenient function to be used for compile-time checks, like:
+	@code{.c}
 	#if HID_API_VERSION >= HID_API_MAKE_VERSION(0, 12, 0)
+	@endcode
 
 	@ingroup API
 */
@@ -103,10 +105,11 @@
 #ifdef __cplusplus
 extern "C" {
 #endif
+		/** A structure to hold the version numbers. */
 		struct hid_api_version {
-			int major;
-			int minor;
-			int patch;
+			int major; /**< major version number */
+			int minor; /**< minor version number */
+			int patch; /**< patch version number */
 		};
 
 		struct hid_device_;
@@ -117,27 +120,27 @@ extern "C" {
 			@ingroup API
 		*/
 		typedef enum {
-			/* Unknown bus type */
+			/** Unknown bus type */
 			HID_API_BUS_UNKNOWN = 0x00,
 
-			/* USB bus
+			/** USB bus
 			   Specifications:
 			   https://usb.org/hid */
 			HID_API_BUS_USB = 0x01,
 
-			/* Bluetooth or Bluetooth LE bus
+			/** Bluetooth or Bluetooth LE bus
 			   Specifications:
 			   https://www.bluetooth.com/specifications/specs/human-interface-device-profile-1-1-1/
 			   https://www.bluetooth.com/specifications/specs/hid-service-1-0/
 			   https://www.bluetooth.com/specifications/specs/hid-over-gatt-profile-1-0/ */
 			HID_API_BUS_BLUETOOTH = 0x02,
 
-			/* I2C bus
+			/** I2C bus
 			   Specifications:
 			   https://docs.microsoft.com/previous-versions/windows/hardware/design/dn642101(v=vs.85) */
 			HID_API_BUS_I2C = 0x03,
 
-			/* SPI bus
+			/** SPI bus
 			   Specifications:
 			   https://www.microsoft.com/download/details.aspx?id=103325 */
 			HID_API_BUS_SPI = 0x04,
@@ -619,4 +622,3 @@ extern "C" {
 #endif
 
 #endif
-