Update Doxygen documentation

This updates the Doxygen documentation so that the generated
documentation is more readable and accessible to users of libx52

Doxyfile.in

@@ -44,7 +44,7 @@ PROJECT_NUMBER         = @PACKAGE_VERSION@
 # for a project that appears at the top of each page and should give viewer a
 # quick idea about the purpose of the project. Keep the description short.
 
-PROJECT_BRIEF          = "Saitek X52 Controller for Unix/Linux"
+PROJECT_BRIEF          = "Saitek X52/X52Pro drivers for Linux/Unix"
 
 # With the PROJECT_LOGO tag one can specify a logo or an icon that is included
 # in the documentation. The maximum height of the logo should not exceed 55

lib/libx52/Makefile.am

@@ -25,3 +25,10 @@ pkgconfig_DATA = libx52.pc
 
 # Extra files that need to be in the distribution
 EXTRA_DIST = libx52.h x52_commands.h x52_common.h README.md
+
+# Add documentation files to the distribution
+EXTRA_DIST += \
+	doc/main.dox \
+	doc/api.dox \
+	doc/caveats.dox \
+	doc/integration.dox

lib/libx52/doc/api.dox

@@ -0,0 +1,40 @@
+/**
+@page libx52_api Application Programming Interface
+
+This is the complete list of libx52 functions, structures and enumerations
+in alphabetical order.
+
+@section functions Functions
+
+- @ref libx52_check_feature
+- @ref libx52_exit
+- @ref libx52_init
+- @ref libx52_set_blink
+- @ref libx52_set_brightness
+- @ref libx52_set_clock
+- @ref libx52_set_clock_format
+- @ref libx52_set_clock_timezone
+- @ref libx52_set_date
+- @ref libx52_set_date_format
+- @ref libx52_set_led_state
+- @ref libx52_set_shift
+- @ref libx52_set_text
+- @ref libx52_set_time
+- @ref libx52_update
+- @ref libx52_vendor_command
+
+@section structs Structures
+
+- @ref libx52_device
+
+@section enums Enumerations
+
+- @ref libx52_clock_format
+- @ref libx52_clock_id
+- @ref libx52_date_format
+- @ref libx52_error_code
+- @ref libx52_feature
+- @ref libx52_led_id
+- @ref libx52_led_state
+
+*/

lib/libx52/doc/caveats.dox

@@ -0,0 +1,26 @@
+/**
+@page libx52_caveats Caveats
+
+@section general General Caveats
+
+libx52 uses [libusb](https://libusb.info) under the hood. Therefore, any
+[caveats](http://libusb.sourceforge.net/api-1.0/libusb_caveats.html) that apply
+to libusb also apply to libx52.
+
+@section threads Thread Safety
+
+libx52 is not designed to be thread-safe. The application must ensure that
+calls to libx52 from multiple threads are protected by a semaphore/mutex.
+
+@section hotplug Hotplugging
+
+libx52 does not support hotplugging. The joystick must be plugged in prior to
+the application initializing libx52.
+
+@section leds LED Support
+
+The Saitek X52 does not support controlling the color of individual LEDs. This
+is only supported on the X52 Pro. The application can use \ref
+libx52_check_feature to verify support.
+
+*/

lib/libx52/doc/integration.dox

@@ -0,0 +1,66 @@
+/**
+@page libx52_integration Integration
+
+libx52 performs all its operations with a device context pointer. The
+application must call \ref libx52_init before performing any operation, and
+must call \ref libx52_exit prior to terminating.
+
+<b>Example Initialization/Deinitialization Code</b>
+
+@code{.c}
+#include <libx52.h>
+
+libx52_device* init_libx52(void)
+{
+    libx52_device *dev;
+    int rc;
+
+    // Initialize the libx52 library
+    rc = libx52_init(&dev);
+    if (rc != LIBX52_SUCCESS) {
+        fputs(libx52_strerror(rc), stderr);
+        return NULL;
+    }
+
+    return dev;
+}
+
+// Close the library and any associated devices
+libx52_exit(dev);
+@endcode
+
+# Joystick Updates
+
+Most libx52 functions to update the joystick state do not directly write to the
+connected joystick, but only update internal data structures within the device
+context. In order to actually update the joystick, the application must call
+\ref libx52_update. This function writes the updates to the joystick and resets
+any internal state.
+
+\b Example
+
+@code{.c}
+libx52_set_text(dev, 0, " Saitek X52 Pro ", 16);
+libx52_set_text(dev, 1, "     Flight     ", 16);
+libx52_set_text(dev, 2, " Control System ", 16);
+libx52_update(dev);
+@endcode
+
+# Error handling
+
+Most libx52 functions return a standard \ref libx52_error_code integer value
+that indicates the status of the operation. As long as the operation succeeded,
+the function will return \ref LIBX52_SUCCESS. Other values returned indicate a
+failure of some sort.
+
+\ref libx52_strerror can convert the return code into a descriptive string that
+may be displayed to users.
+
+## Internationalization of error strings
+
+\ref libx52_strerror automatically handles internationalization. As long as your
+application sets up the locale correctly, and the error strings have been
+translated to that locale, the returned strings will correspond to the translated
+values for your locale.
+
+*/

lib/libx52/doc/main.dox

@@ -0,0 +1,35 @@
+/**
+@mainpage Saitek X52/X52Pro drivers for Linux/Unix
+
+@section intro Introduction
+
+libx52 is an open source library that allows you to communicate with a
+Saitek X52 or Saitek X52Pro joystick on Linux and Unix machines. Saitek
+only provides Windows drivers for their joysticks, necessitating the need
+for this project for users to be able to control the LEDs and MFD text on
+a Linux or Unix device.
+
+This documentation is intended for application developers who wish to use
+the features of this library to communicate with supported devices.
+
+@section start Getting Started
+
+See the @ref libx52_integration page for details on how to integrate libx52
+with your application.
+
+@section features Library Features
+
+libx52 supports setting the following parameters on the joystick
+
+1. Text on the multifunction display (MFD).
+2. All 3 clocks on the MFD.
+4. Date display on the MFD.
+5. Blinking of the POV hat and clutch LEDs (both blinking or not).
+6. Shift indicator on the MFD.
+7. Setting the color of the individual LEDs (*on the X52 Pro only*).
+
+@section api Application Programming Interface
+
+See the @ref libx52_api for a complete list of all functions.
+
+*/

lib/libx52/libx52.h

@@ -23,7 +23,7 @@ extern "C" {
 struct libx52_device;
 
 /**
- * @brief Opaque structure used by libx52
+ * @brief Device context structure used by libx52
  * @ingroup libx52init
  */
 typedef struct libx52_device libx52_device;
@@ -200,9 +200,9 @@ typedef enum {
 /**
  * @brief Feature support for libx52
  *
- * Each flag is passed to \ref libx52_has_feature to determine if the connected
+ * Each flag is passed to \ref libx52_check_feature to determine if the
- * device has the given feature. This list of features is only limited to those
+ * connected device has the given feature. This list of features is only
- * which differ between the supported devices.
+ * limited to those which differ between the supported devices.
  *
  * @ingroup libx52misc
  */
@@ -214,6 +214,9 @@ typedef enum {
 
 /**
  * @defgroup libx52init Library Initialization and Deinitialization
+ *
+ * These functions are used at application entry and exit.
+ *
  * @{
  */
 
@@ -230,7 +233,8 @@ typedef enum {
  * This function does not support hotplugging. The joystick must be plugged in
  * before calling this function.
  *
- * @param[out]  dev     Pointer to a \ref libx52_device *
+ * @param[out]  dev     Pointer to a \ref libx52_device *. This function will
+ * allocate a device context and return the pointer to that in this variable.
  *
  * @returns \ref libx52_error_code indicating status
  */
@@ -243,7 +247,7 @@ int libx52_init(libx52_device ** dev);
  * terminates the library. Using the freed device now is invalid and can
  * cause errors.
  *
- * @param[in]   dev     Pointer to the device
+ * @param[in]   dev     Pointer to the device context
  * @returns None
  */
 void libx52_exit(libx52_device *dev);
@@ -251,7 +255,10 @@ void libx52_exit(libx52_device *dev);
 /** @} */
 
 /**
- * @defgroup mfdled MFD & LED control
+ * @defgroup libx52mfdled MFD & LED control
+ *
+ * Control the MFD text and LED states
+ *
  * @{
  */
 
@@ -272,7 +279,7 @@ void libx52_exit(libx52_device *dev);
  * This function can only store a maximum of 16 characters per line. Any
  * additional characters are silently discarded.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   line    Line to be updated (0, 1 or 2)
  * @param[in]   text    Pointer to the text string. The text must be mapped to
  *                      the code page of the X52 display.
@@ -295,7 +302,7 @@ int libx52_set_text(libx52_device *x52, uint8_t line, const char *text, uint8_t
  * \ref LIBX52_LED_STATE_ON. The remaining LEDs support all the states with
  * the exception of \ref LIBX52_LED_STATE_ON.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   led     LED identifier (refer \ref libx52_led_id)
  * @param[in]   state   State of the LED (refer \ref libx52_led_state)
  *
@@ -313,6 +320,9 @@ int libx52_set_led_state(libx52_device *x52,
 
 /**
  * @defgroup libx52clock Clock control
+ *
+ * Control the clocks on the MFD
+ *
  * @{
  */
 
@@ -333,7 +343,7 @@ int libx52_set_led_state(libx52_device *x52,
  * The secondary and tertiary clocks are driven off the primary clock and set
  * using \ref libx52_set_clock_timezone.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   time    Time value from \c time(3)
  * @param[in]   local   0 for GM time, non-zero for localtime
  *
@@ -352,7 +362,7 @@ int libx52_set_clock(libx52_device *x52, time_t time, int local);
  * from GMT. \p offset is limited to +/- 1440 minutes, and any offset outside
  * this range will result in a return value of \ref LIBX52_ERROR_OUT_OF_RANGE
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   clock   \ref libx52_clock_id, cannot be \ref
  *                      LIBX52_CLOCK_1
  * @param[in]   offset  Offset in minutes from GMT (east is positive, west
@@ -377,7 +387,7 @@ int libx52_set_clock_timezone(libx52_device *x52,
  * The hardware has a limitation that it cannot display 12:00 am in 12 hour
  * mode - instead it will display as 00:00 am
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   clock   \ref libx52_clock_id
  * @param[in]   format  \ref libx52_clock_format
  *
@@ -395,7 +405,7 @@ int libx52_set_clock_format(libx52_device *x52,
  * so desires, however, it will not update the timezone or the date
  * values.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   hour    Hour to display
  * @param[in]   minute  Minute to display
  *
@@ -409,7 +419,7 @@ int libx52_set_time(libx52_device *x52, uint8_t hour, uint8_t minute);
  * This is a raw API which can be used for manual control if the user
  * so desires, however, it will not update the timezone or the time values.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   dd      Day to display
  * @param[in]   mm      Month to display
  * @param[in]   yy      Year to display
@@ -423,7 +433,7 @@ int libx52_set_date(libx52_device *x52, uint8_t dd, uint8_t mm, uint8_t yy);
  *
  * If not set, the date format defaults to DD-MM-YY
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   format  \ref libx52_date_format
  *
  * @returns 0 on success, \ref LIBX52_ERROR_INVALID_PARAM if \p x52 is not valid
@@ -445,7 +455,7 @@ int libx52_set_date_format(libx52_device *x52, libx52_date_format format);
  * the library does not fail on values higher than 128, the effect may not
  * be what is intended.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   mfd     0 for LED brightness, 1 for MFD brightness
  * @param[in]   brightness  Brightness level to set
  *
@@ -459,7 +469,7 @@ int libx52_set_brightness(libx52_device *x52, uint8_t mfd, uint16_t brightness);
  * The X52 Pro MFD has a single shift indicator that indicates when the
  * "shift" button is pressed.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   state   0 for off, 1 for on
  *
  * @returns 0 on success, \ref LIBX52_ERROR_INVALID_PARAM if \p x52 is not valid
@@ -471,7 +481,7 @@ int libx52_set_shift(libx52_device *x52, uint8_t state);
  *
  * The X52 Pro has a "blink" state where it blinks the clutch and hat LEDs.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   state   0 for off, 1 for on
  *
  * @returns 0 on success, \ref LIBX52_ERROR_INVALID_PARAM if \p x52 is not valid
@@ -485,7 +495,7 @@ int libx52_set_blink(libx52_device *x52, uint8_t state);
  * not actually write anything to the joystick. This function writes the saved
  * data to the joystick and updates the internal data structures as necessary.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  *
  * @returns 0 on success, \ref LIBX52_ERROR_USB_FAILURE on failure
  */
@@ -495,6 +505,9 @@ int libx52_update(libx52_device *x52);
 
 /**
  * @defgroup libx52misc Miscellaneous
+ *
+ * Miscellaneous functionality
+ *
  * @{
  */
 
@@ -507,7 +520,7 @@ int libx52_update(libx52_device *x52);
  * This can be used to debug issues seen on the hardware, however, it is \b NOT
  * recommended for use by end users, as it can potentially damage the hardware.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   index   wIndex in the USB packet
  * @param[in]   value   wValue in the USB packet
  *
@@ -523,7 +536,7 @@ int libx52_vendor_command(libx52_device *x52, uint16_t index, uint16_t value);
  * \ref LIBX52_ERROR_NOT_SUPPORTED if it does not, and another \ref
  * libx52_error_code on errors.
  *
- * @param[in]   x52     Pointer to the device
+ * @param[in]   x52     Pointer to the device context
  * @param[in]   feature Feature identifier (\ref libx52_feature)
  *
  * @returns \ref libx52_error_code indicating status
@@ -540,6 +553,8 @@ int libx52_check_feature(libx52_device *x52, libx52_feature feature);
  */
 const char * libx52_strerror(libx52_error_code error);
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif