diff --git a/Doxyfile.in b/Doxyfile.in
index 4702559..ec7ebe7 100644
--- a/Doxyfile.in
+++ b/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
diff --git a/lib/libx52/Makefile.am b/lib/libx52/Makefile.am
index 0c7ae5e..f5ba420 100644
--- a/lib/libx52/Makefile.am
+++ b/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
diff --git a/lib/libx52/doc/api.dox b/lib/libx52/doc/api.dox
new file mode 100644
index 0000000..9f58ab5
--- /dev/null
+++ b/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
+
+*/
diff --git a/lib/libx52/doc/caveats.dox b/lib/libx52/doc/caveats.dox
new file mode 100644
index 0000000..96c4b93
--- /dev/null
+++ b/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.
+
+*/
diff --git a/lib/libx52/doc/integration.dox b/lib/libx52/doc/integration.dox
new file mode 100644
index 0000000..66ccf5a
--- /dev/null
+++ b/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.
+
+Example Initialization/Deinitialization Code
+
+@code{.c}
+#include
+
+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.
+
+*/
diff --git a/lib/libx52/doc/main.dox b/lib/libx52/doc/main.dox
new file mode 100644
index 0000000..0d9c4f0
--- /dev/null
+++ b/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.
+
+*/
diff --git a/lib/libx52/libx52.h b/lib/libx52/libx52.h
index 9bdd6d4..7254f1c 100644
--- a/lib/libx52/libx52.h
+++ b/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
- * device has the given feature. This list of features is only limited to those
- * which differ between the supported devices.
+ * Each flag is passed to \ref libx52_check_feature to determine if the
+ * connected device has the given feature. This list of features is only
+ * 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