From dfdf6468bce30d80bc90bc4b3c7aa3aa607d391b Mon Sep 17 00:00:00 2001 From: nirenjan Date: Fri, 22 May 2020 18:04:18 -0700 Subject: [PATCH] Update Doxygen documentation This updates the Doxygen documentation so that the generated documentation is more readable and accessible to users of libx52 --- Doxyfile.in | 2 +- lib/libx52/Makefile.am | 7 ++++ lib/libx52/doc/api.dox | 40 +++++++++++++++++++++ lib/libx52/doc/caveats.dox | 26 ++++++++++++++ lib/libx52/doc/integration.dox | 66 ++++++++++++++++++++++++++++++++++ lib/libx52/doc/main.dox | 35 ++++++++++++++++++ lib/libx52/libx52.h | 57 ++++++++++++++++++----------- 7 files changed, 211 insertions(+), 22 deletions(-) create mode 100644 lib/libx52/doc/api.dox create mode 100644 lib/libx52/doc/caveats.dox create mode 100644 lib/libx52/doc/integration.dox create mode 100644 lib/libx52/doc/main.dox 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