Update Doxygen comments

This disables the include file list and dependency graph in the file
view. In addition, the groups are updated to include `libx52` in their
names, to avoid any potential conflict.

[skip ci]

Doxyfile.in

@@ -582,7 +582,7 @@ HIDE_COMPOUND_REFERENCE= NO
 # the files that are included by a file in the documentation of that file.
 # The default value is: YES.
 
-SHOW_INCLUDE_FILES     = YES
+SHOW_INCLUDE_FILES     = NO
 
 # If the SHOW_GROUPED_MEMB_INC tag is set to YES then Doxygen will add for each
 # grouped member an include statement to the documentation, telling the reader
@@ -858,6 +858,7 @@ INPUT_ENCODING         = UTF-8
 
 FILE_PATTERNS          = \
                          libx52.h \
+                         libx52util.h \
                          *.dox
 
 # The RECURSIVE tag can be used to specify whether or not subdirectories should
@@ -2351,7 +2352,7 @@ TEMPLATE_RELATIONS     = NO
 # The default value is: YES.
 # This tag requires that the tag HAVE_DOT is set to YES.
 
-INCLUDE_GRAPH          = YES
+INCLUDE_GRAPH          = NO
 
 # If the INCLUDED_BY_GRAPH, ENABLE_PREPROCESSING and SEARCH_INCLUDES tags are
 # set to YES then doxygen will generate a graph for each documented file showing

Makefile.am

@@ -13,8 +13,8 @@ EXTRA_DIST = AUTHORS ChangeLog.md README.md LICENSE Doxyfile.in
 
 # Doxygen support
 if HAVE_DOXYGEN
-docs/.stamp:
+docs/.stamp: Doxyfile
-	$(AM_V_GEN)$(DOXYGEN) Doxyfile
+	$(AM_V_GEN)$(DOXYGEN) $<
 	$(AM_V_at)touch $@
 
 CLEANFILES = docs/.stamp

lib/libx52/libx52.h

@@ -29,18 +29,18 @@ extern "C" {
 
 /**
  * @brief Opaque structure used by libx52
- * @ingroup init
+ * @ingroup libx52init
  */
 struct libx52_device;
 
 /**
  * @brief Opaque structure used by libx52
- * @ingroup init
+ * @ingroup libx52init
  */
 typedef struct libx52_device libx52_device;
 
 /**
- * @addtogroup hotplug
+ * @addtogroup libx52hotplug
  * @{
  */
 
@@ -73,7 +73,7 @@ typedef void (*libx52_hotplug_fn)(bool inserted, void *user_data, libx52_device
 
 /**
  * @brief List of supported clocks on the MFD
- * @ingroup clock
+ * @ingroup libx52clock
  */
 typedef enum {
     /** Primary clock on the MFD, indicated by the number 1 */
@@ -88,7 +88,7 @@ typedef enum {
 
 /**
  * @brief Supported clock formats
- * @ingroup clock
+ * @ingroup libx52clock
  */
 typedef enum {
     /** 12-hour display on the MFD clock */
@@ -100,7 +100,7 @@ typedef enum {
 
 /**
  * @brief Supported date formats
- * @ingroup clock
+ * @ingroup libx52clock
  */
 typedef enum {
     /** Date format DD-MM-YY */
@@ -115,7 +115,7 @@ typedef enum {
 
 /**
  * @brief Supported LED identifiers
- * @ingroup mfdled
+ * @ingroup libx52mfdled
  */
 typedef enum {
     /** Fire indicator LED */
@@ -157,7 +157,7 @@ typedef enum {
  *
  * Not all LEDs support all states
  *
- * @ingroup clock
+ * @ingroup libx52mfdled
  */
 typedef enum {
     /** LED is off */
@@ -184,7 +184,7 @@ typedef enum {
  *
  * Error codes returned by libx52
  *
- * @ingroup misc
+ * @ingroup libx52misc
  */
 typedef enum {
     /** No error, indicates success */
@@ -241,7 +241,7 @@ typedef enum {
 } libx52_error_code;
 
 /**
- * @defgroup init Library Initialization and Deinitialization
+ * @defgroup libx52init Library Initialization and Deinitialization
  * @{
  */
 
@@ -307,7 +307,7 @@ void libx52_hotplug_exit(libx52_hotplug_service *svc);
 /** @} */
 
 /**
- * @defgroup hotplug Hotplug Callbacks
+ * @defgroup libx52hotplug Hotplug Callbacks
  * @{
  */
 
@@ -359,7 +359,7 @@ int libx52_hotplug_deregister_callback(libx52_hotplug_callback_handle *hdl);
 /** @} */
 
 /**
- * @defgroup mfdled MFD & LED control
+ * @defgroup libx52mfdled MFD & LED control
  * @{
  */
 
@@ -420,7 +420,7 @@ int libx52_set_led_state(libx52_device *x52,
 /** @} */
 
 /**
- * @defgroup clock Clock control
+ * @defgroup libx52clock Clock control
  * @{
  */
 
@@ -541,7 +541,7 @@ int libx52_set_date_format(libx52_device *x52, libx52_date_format format);
 /** @} */
 
 /**
- * @addtogroup mfdled
+ * @addtogroup libx52mfdled
  * @{
  */
 
@@ -602,7 +602,7 @@ int libx52_update(libx52_device *x52);
 /** @} */
 
 /**
- * @defgroup misc Miscellaneous
+ * @defgroup libx52misc Miscellaneous
  * @{
  */
 

lib/libx52util/libx52util.h

@@ -6,6 +6,16 @@
  * SPDX-License-Identifier: GPL-2.0-only WITH Classpath-exception-2.0
  */
 
+/**
+ * @file libx52util.h
+ * @brief Utility functions for the Saitek X52 MFD & LED driver library
+ *
+ * This file contains the type and function prototypes for the Saitek X52
+ * driver library utility functions. These functions simplify some of the
+ * data handling for \ref libx52mfdled, but they are not required.
+ *
+ * @author Nirenjan Krishnan (nirenjan@nirenjan.org)
+ */
 #ifndef LIBX52UTIL_H
 #define LIBX52UTIL_H
 
@@ -15,6 +25,14 @@
 extern "C" {
 #endif
 
+/**
+ * @defgroup libx52util Utility Functions
+ *
+ * These functions simplify some of the data handling for \ref libx52mfdled.
+ *
+ * @{
+ */
+
 /**
  * @brief Convert UTF8 string to X52 character map.
  *
@@ -23,7 +41,7 @@ extern "C" {
  *
  * @param[in]       input   Input string in UTF-8. Must be NUL-terminated
  * @param[out]      output  Output buffer
- * @param[inout]    len     Length of output buffer
+ * @param[in,out]   len     Length of output buffer
  *
  * @returns 0 on success, -EINVAL on invalid parameters, -E2BIG if the buffer
  * filled up before converting the entire string.
@@ -31,6 +49,8 @@ extern "C" {
 int libx52util_convert_utf8_string(const uint8_t *input,
                                    uint8_t *output, size_t *len);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif