mirror
/
libx52
mirror of https://github.com/nirenjan/libx52.git
1
0
Fork 0
Code Releases Wiki Activity

Update Doxygen documentation 

This updates the Doxygen documentation so that the generated
documentation is more readable and accessible to users of libx52
debian-packaging
nirenjan 2020-05-22 18:04:18 -07:00
parent fd6afde59c
commit dfdf6468bc
7 changed files with 211 additions and 22 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Doxyfile.in
View File

@ -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

7
lib/libx52/Makefile.am
View File

@ -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

40
lib/libx52/doc/api.dox 100644
View File

@ -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
*/

26
lib/libx52/doc/caveats.dox 100644
View File

@ -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.
*/

66
lib/libx52/doc/integration.dox 100644
View File

@ -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.
*/

35
lib/libx52/doc/main.dox 100644
View File

@ -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.
*/

57
lib/libx52/libx52.h
View File

@ -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