From 51674ce9ded7806af39a80a24ad79569914813ed Mon Sep 17 00:00:00 2001 From: Ryan Pavlik Date: Mon, 2 May 2011 10:05:45 -0500 Subject: [PATCH] improve doxygen output. --- Doxyfile | 16 ++++---- src/classic.h | 3 ++ src/definitions.h | 6 +++ src/dynamics.h | 4 ++ src/events.h | 4 ++ src/guitar_hero_3.h | 4 ++ src/io.h | 4 ++ src/ir.h | 4 ++ src/nunchuk.h | 4 ++ src/wiiboard.h | 6 ++- src/wiiuse.h | 95 +++++++++++++++++++++++++------------------ src/wiiuse_internal.h | 8 +++- 12 files changed, 108 insertions(+), 50 deletions(-) diff --git a/Doxyfile b/Doxyfile index 75c9960..5fde9f9 100644 --- a/Doxyfile +++ b/Doxyfile @@ -80,14 +80,14 @@ OUTPUT_LANGUAGE = English # the file and class documentation (similar to JavaDoc). # Set to NO to disable this. -BRIEF_MEMBER_DESC = YES +BRIEF_MEMBER_DESC = NO # If the REPEAT_BRIEF tag is set to YES (the default) Doxygen will prepend # the brief description of a member or function before the detailed description. # Note: if both HIDE_UNDOC_MEMBERS and BRIEF_MEMBER_DESC are set to NO, the # brief descriptions will be completely suppressed. -REPEAT_BRIEF = YES +REPEAT_BRIEF = NO # This tag implements a quasi-intelligent brief description abbreviator # that is used to form the text in various listings. Each string @@ -209,7 +209,7 @@ ALIASES = # For instance, some of the names that are used will be different. The list # of all members will be omitted, etc. -OPTIMIZE_OUTPUT_FOR_C = NO +OPTIMIZE_OUTPUT_FOR_C = YES # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java # sources only. Doxygen will then generate output that is more tailored for @@ -321,17 +321,17 @@ SYMBOL_CACHE_SIZE = 0 # Private class members and static file members will be hidden unless # the EXTRACT_PRIVATE and EXTRACT_STATIC tags are set to YES -EXTRACT_ALL = YES +EXTRACT_ALL = NO # If the EXTRACT_PRIVATE tag is set to YES all private members of a class # will be included in the documentation. -EXTRACT_PRIVATE = YES +EXTRACT_PRIVATE = NO # If the EXTRACT_STATIC tag is set to YES all static members of a file # will be included in the documentation. -EXTRACT_STATIC = YES +EXTRACT_STATIC = NO # If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs) # defined locally in source files will be included in the documentation. @@ -449,7 +449,7 @@ SORT_MEMBERS_CTORS_1ST = NO # hierarchy of group names into alphabetical order. If set to NO (the default) # the group names will appear in their defined order. -SORT_GROUP_NAMES = NO +SORT_GROUP_NAMES = YES # If the SORT_BY_SCOPE_NAME tag is set to YES, the class list will be # sorted by fully-qualified names, including namespaces. If set to @@ -1124,7 +1124,7 @@ MATHJAX_RELPATH = http://www.mathjax.org/mathjax # typically be disabled. For large projects the javascript based search engine # can be slow, then enabling SERVER_BASED_SEARCH may provide a better solution. -SEARCHENGINE = NO +SEARCHENGINE = YES # When the SERVER_BASED_SEARCH tag is enabled the search engine will be # implemented using a PHP enabled web server instead of at the web client diff --git a/src/classic.h b/src/classic.h index 356f6a4..cc9fd64 100644 --- a/src/classic.h +++ b/src/classic.h @@ -40,11 +40,14 @@ extern "C" { #endif +/** @defgroup internal_classic Internal: Classic Controller */ +/** @{ */ int classic_ctrl_handshake(struct wiimote_t* wm, struct classic_ctrl_t* cc, byte* data, unsigned short len); void classic_ctrl_disconnected(struct classic_ctrl_t* cc); void classic_ctrl_event(struct classic_ctrl_t* cc, byte* msg); +/** @} */ #ifdef __cplusplus } diff --git a/src/definitions.h b/src/definitions.h index 76da35d..a7bb252 100644 --- a/src/definitions.h +++ b/src/definitions.h @@ -37,6 +37,8 @@ /* this is wiiuse - used to distinguish from third party programs using wiiuse.h */ #include #include "os.h" +/** @addtogroup internal_general */ +/** @{ */ #define WIIMOTE_PI 3.14159265f @@ -87,4 +89,8 @@ extern FILE* logtarget[]; #define diff_f(x, y) ((x >= y) ? (absf(x - y)) : (absf(y - x))) #define WCONST + + +/** @} */ + #endif // DEFINITIONS_H_INCLUDED diff --git a/src/dynamics.h b/src/dynamics.h index 2a8f965..1505401 100644 --- a/src/dynamics.h +++ b/src/dynamics.h @@ -44,10 +44,14 @@ extern "C" { #endif +/** @defgroup internal_dynamics Internal: Dynamics Functions */ +/** @{ */ + void calculate_orientation(struct accel_t* ac, struct vec3b_t* accel, struct orient_t* orient, int smooth); void calculate_gforce(struct accel_t* ac, struct vec3b_t* accel, struct gforce_t* gforce); void calc_joystick_state(struct joystick_t* js, float x, float y); void apply_smoothing(struct accel_t* ac, struct orient_t* orient, int type); +/** @} */ #ifdef __cplusplus } diff --git a/src/events.h b/src/events.h index 4363bcd..c3629e5 100644 --- a/src/events.h +++ b/src/events.h @@ -47,9 +47,13 @@ #include #endif + +/** @defgroup internal_events Internal: Event Utilities */ +/** @{ */ void wiiuse_pressed_buttons(struct wiimote_t* wm, byte* msg); void handshake_expansion(struct wiimote_t* wm, byte* data, uint16_t len); void disable_expansion(struct wiimote_t* wm); +/** @} */ #endif // EVENTS_H_INCLUDED diff --git a/src/guitar_hero_3.h b/src/guitar_hero_3.h index 024d603..e38e0b0 100644 --- a/src/guitar_hero_3.h +++ b/src/guitar_hero_3.h @@ -49,11 +49,15 @@ extern "C" { #endif + +/** @defgroup internal_gh3 Internal: Guitar Hero 3 controller */ +/** @{ */ int guitar_hero_3_handshake(struct wiimote_t* wm, struct guitar_hero_3_t* gh3, byte* data, unsigned short len); void guitar_hero_3_disconnected(struct guitar_hero_3_t* gh3); void guitar_hero_3_event(struct guitar_hero_3_t* gh3, byte* msg); +/** @} */ #ifdef __cplusplus } diff --git a/src/io.h b/src/io.h index 7c5fd97..4c7d31d 100644 --- a/src/io.h +++ b/src/io.h @@ -44,10 +44,14 @@ extern "C" { #endif + +/** @defgroup internal_io Internal: Device IO */ +/** @{ */ void wiiuse_handshake(struct wiimote_t* wm, byte* data, uint16_t len); int wiiuse_io_read(struct wiimote_t* wm); int wiiuse_io_write(struct wiimote_t* wm, byte* buf, int len); +/** @} */ #ifdef __cplusplus } diff --git a/src/ir.h b/src/ir.h index 9082492..1719c73 100644 --- a/src/ir.h +++ b/src/ir.h @@ -43,9 +43,13 @@ extern "C" { #endif + +/** @defgroup internal_ir Internal: IR Sensor */ +/** @{ */ void calculate_basic_ir(struct wiimote_t* wm, byte* data); void calculate_extended_ir(struct wiimote_t* wm, byte* data); float calc_yaw(struct ir_t* ir); +/** @} */ #ifdef __cplusplus } diff --git a/src/nunchuk.h b/src/nunchuk.h index f036073..794f6c6 100644 --- a/src/nunchuk.h +++ b/src/nunchuk.h @@ -40,11 +40,15 @@ extern "C" { #endif + +/** @defgroup internal_nunchuk Internal: Nunchuk */ +/** @{ */ int nunchuk_handshake(struct wiimote_t* wm, struct nunchuk_t* nc, byte* data, unsigned short len); void nunchuk_disconnected(struct nunchuk_t* nc); void nunchuk_event(struct nunchuk_t* nc, byte* msg); +/** @} */ #ifdef __cplusplus } diff --git a/src/wiiboard.h b/src/wiiboard.h index 2c49029..0b175e2 100644 --- a/src/wiiboard.h +++ b/src/wiiboard.h @@ -28,7 +28,7 @@ /** * @file - * @brief Wii board expansion device. + * @brief Wii balance board expansion device. */ #ifndef WII_BOARD_H_INCLUDED @@ -40,12 +40,14 @@ extern "C" { #endif +/** @defgroup internal_wiiboard Internal: Wii Balance Board */ +/** @{ */ int wii_board_handshake(struct wiimote_t* wm, struct wii_board_t* wb, byte* data, uint16_t len); void wii_board_disconnected(struct wii_board_t* wb); void wii_board_event(struct wii_board_t* wb, byte* msg); - +/** @} */ #ifdef __cplusplus } #endif diff --git a/src/wiiuse.h b/src/wiiuse.h index 1fa6032..acd32ec 100644 --- a/src/wiiuse.h +++ b/src/wiiuse.h @@ -39,20 +39,27 @@ /** * @mainpage * + * @section intro Introduction + * + * WiiUse is a cross-platform C library for accessing the Nintendo Wii + * Remote and its related expansions and variations. + * * @section project Project * * This is a friendly fork of the original WiiUse project, which seems - * to have gone defunct. This updated version is maintained at: + * to have gone defunct. This updated version incorporates improvements + * from a number of internal forks found across the Internet, and is + * intended to be the new "upstream" of the project. The new homepage is + * on GitHub, where the source is maintained: * * - http://github.com/rpavlik/wiiuse * + * Contributions (under the GPL 3+) are welcome and encouraged! + * * @section publicapisec Public API * - * The full public API for WiiUse is found in @ref wiiuse.h - * - * @section quicklinks API Docs Quick Links - * - @ref wiiuse.h - * - @ref wiimote structure + * - @ref publicapi "Public API" - entirely within @ref wiiuse.h + * - @ref wiimote "Wiimote device structure" * */ #ifndef WIIUSE_H_INCLUDED @@ -84,14 +91,20 @@ #include #endif -/* led bit masks */ +/** @defgroup publicapi External API */ +/** @{ */ + +/** @name LED bit masks */ +/** @{ */ #define WIIMOTE_LED_NONE 0x00 #define WIIMOTE_LED_1 0x10 #define WIIMOTE_LED_2 0x20 #define WIIMOTE_LED_3 0x40 #define WIIMOTE_LED_4 0x80 +/** @} */ -/* button codes */ +/** @name Button codes */ +/** @{ */ #define WIIMOTE_BUTTON_TWO 0x0001 #define WIIMOTE_BUTTON_ONE 0x0002 #define WIIMOTE_BUTTON_B 0x0004 @@ -109,13 +122,17 @@ #define WIIMOTE_BUTTON_ZACCEL_BIT5 0x4000 #define WIIMOTE_BUTTON_UNKNOWN 0x8000 #define WIIMOTE_BUTTON_ALL 0x1F9F +/** @} */ -/* nunchul button codes */ +/** @name Nunchuk button codes */ +/** @{ */ #define NUNCHUK_BUTTON_Z 0x01 #define NUNCHUK_BUTTON_C 0x02 #define NUNCHUK_BUTTON_ALL 0x03 +/** @} */ -/* classic controller button codes */ +/** @name Classic controller button codes */ +/** @{ */ #define CLASSIC_CTRL_BUTTON_UP 0x0001 #define CLASSIC_CTRL_BUTTON_LEFT 0x0002 #define CLASSIC_CTRL_BUTTON_ZR 0x0004 @@ -132,8 +149,10 @@ #define CLASSIC_CTRL_BUTTON_DOWN 0x4000 #define CLASSIC_CTRL_BUTTON_RIGHT 0x8000 #define CLASSIC_CTRL_BUTTON_ALL 0xFEFF +/** @} */ -/* guitar hero 3 button codes */ +/** @name Guitar Hero 3 button codes */ +/** @{ */ #define GUITAR_HERO_3_BUTTON_STRUM_UP 0x0001 #define GUITAR_HERO_3_BUTTON_YELLOW 0x0008 #define GUITAR_HERO_3_BUTTON_GREEN 0x0010 @@ -144,29 +163,36 @@ #define GUITAR_HERO_3_BUTTON_MINUS 0x1000 #define GUITAR_HERO_3_BUTTON_STRUM_DOWN 0x4000 #define GUITAR_HERO_3_BUTTON_ALL 0xFEFF +/** @} */ - -/* wiimote option flags */ +/** @name Wiimote option flags */ +/** @{ */ #define WIIUSE_SMOOTHING 0x01 #define WIIUSE_CONTINUOUS 0x02 #define WIIUSE_ORIENT_THRESH 0x04 #define WIIUSE_INIT_FLAGS (WIIUSE_SMOOTHING | WIIUSE_ORIENT_THRESH) #define WIIUSE_ORIENT_PRECISION 100.0f +/** @} */ -/* expansion codes */ +/** @name Expansion codes */ +/** @{ */ #define EXP_NONE 0 #define EXP_NUNCHUK 1 #define EXP_CLASSIC 2 #define EXP_GUITAR_HERO_3 3 #define EXP_WII_BOARD 4 +/** @} */ -/* IR correction types */ +/** @brief IR correction types */ typedef enum ir_position_t { WIIUSE_IR_ABOVE, WIIUSE_IR_BELOW } ir_position_t; + +/** @name Device Inquiry Macros */ +/** @{ */ /** * @brief Check if a button is pressed. * @param dev Pointer to a wiimote_t or expansion structure. @@ -224,6 +250,7 @@ typedef enum ir_position_t { #define WIIUSE_USING_SPEAKER(wm) ((wm->state & 0x100) == 0x100) #define WIIUSE_IS_LED_SET(wm, num) ((wm->leds & WIIMOTE_LED_##num) == WIIMOTE_LED_##num) +/** @} */ /* * Largest known payload is 21 bytes. @@ -266,7 +293,6 @@ typedef void (*wiiuse_read_cb)(struct wiimote_t* wm, byte* data, uint16_t len); /** - * @struct read_req_t * @brief Data read request structure. */ struct read_req_t { @@ -282,7 +308,6 @@ struct read_req_t { /** - * @struct vec2b_t * @brief Unsigned x,y byte vector. */ typedef struct vec2b_t { @@ -291,7 +316,6 @@ typedef struct vec2b_t { /** - * @struct vec3b_t * @brief Unsigned x,y,z byte vector. */ typedef struct vec3b_t { @@ -300,7 +324,6 @@ typedef struct vec3b_t { /** - * @struct vec3f_t * @brief Signed x,y,z float struct. */ typedef struct vec3f_t { @@ -309,7 +332,6 @@ typedef struct vec3f_t { /** - * @struct orient_t * @brief Orientation struct. * * Yaw, pitch, and roll range from -180 to 180 degrees. @@ -325,7 +347,6 @@ typedef struct orient_t { /** - * @struct gforce_t * @brief Gravity force struct. */ typedef struct gforce_t { @@ -334,7 +355,6 @@ typedef struct gforce_t { /** - * @struct accel_t * @brief Accelerometer struct. For any device with an accelerometer. */ typedef struct accel_t { @@ -348,7 +368,6 @@ typedef struct accel_t { /** - * @struct ir_dot_t * @brief A single IR source. */ typedef struct ir_dot_t { @@ -367,7 +386,6 @@ typedef struct ir_dot_t { /** - * @enum aspect_t * @brief Screen aspect ratio. */ typedef enum aspect_t { @@ -377,7 +395,6 @@ typedef enum aspect_t { /** - * @struct ir_t * @brief IR struct. Hold all data related to the IR tracking. */ typedef struct ir_t { @@ -404,7 +421,6 @@ typedef struct ir_t { /** - * @struct joystick_t * @brief Joystick calibration structure. * * The angle \a ang is relative to the positive y-axis into quadrant I @@ -429,7 +445,6 @@ typedef struct joystick_t { /** - * @struct nunchuk_t * @brief Nunchuk expansion device. */ typedef struct nunchuk_t { @@ -452,7 +467,6 @@ typedef struct nunchuk_t { /** - * @struct classic_ctrl_t * @brief Classic controller expansion device. */ typedef struct classic_ctrl_t { @@ -469,7 +483,6 @@ typedef struct classic_ctrl_t { /** - * @struct guitar_hero_3_t * @brief Guitar Hero 3 expansion device. */ typedef struct guitar_hero_3_t { @@ -482,9 +495,12 @@ typedef struct guitar_hero_3_t { struct joystick_t js; /**< joystick calibration */ } guitar_hero_3_t; -/* - Wii board -*/ +/** + * @brief Wii Balance Board "expansion" device. + * + * A Balance Board presents itself as a Wiimote with a permanently-attached + * Balance Board expansion device. + */ typedef struct wii_board_t { float tl; /* Interpolated */ float tr; @@ -503,7 +519,6 @@ typedef struct wii_board_t { /** - * @struct expansion_t * @brief Generic expansion device plugged into wiimote. */ typedef struct expansion_t { @@ -519,7 +534,6 @@ typedef struct expansion_t { /** - * @enum win32_bt_stack_t * @brief Available bluetooth stacks for Windows. */ typedef enum win_bt_stack_t { @@ -530,7 +544,6 @@ typedef enum win_bt_stack_t { /** - * @struct wiimote_state_t * @brief Significant data from the previous event. */ typedef struct wiimote_state_t { @@ -564,7 +577,6 @@ typedef struct wiimote_state_t { /** - * @enum WIIUSE_EVENT_TYPE * @brief Events that wiiuse can generate from a poll. */ typedef enum WIIUSE_EVENT_TYPE { @@ -586,8 +598,9 @@ typedef enum WIIUSE_EVENT_TYPE { } WIIUSE_EVENT_TYPE; /** - * @struct wiimote_t - * @brief Wiimote structure. + * @brief Main Wiimote device structure. + * + * You need one of these to do pretty much anything with this library. */ typedef struct wiimote_t { WCONST int unid; /**< user specified id */ @@ -638,7 +651,6 @@ typedef struct wiimote_t { } wiimote; /** - * @enum WIIUSE_LOGLEVEL * @brief Loglevels supported by wiiuse. */ typedef enum wiiuse_loglevel { @@ -674,6 +686,10 @@ extern "C" { /* wiiuse.c */ WIIUSE_EXPORT extern const char* wiiuse_version(); + +/** @brief Define indicating the presence of the feature allowing you to + * redirect output for one or more logging levels within the library. + */ #define WIIUSE_HAS_OUTPUT_REDIRECTION WIIUSE_EXPORT extern void wiiuse_set_output(enum wiiuse_loglevel loglevel, FILE *logtarget); @@ -723,6 +739,7 @@ WIIUSE_EXPORT extern void wiiuse_set_wii_board_calib(struct wiimote_t *wm); } #endif +/** @} */ #endif /* WIIUSE_H_INCLUDED */ diff --git a/src/wiiuse_internal.h b/src/wiiuse_internal.h index de25bf0..5df38e9 100644 --- a/src/wiiuse_internal.h +++ b/src/wiiuse_internal.h @@ -69,6 +69,9 @@ * ********************/ + +/** @addtogroup internal_general Internal: API for General Internal Use */ +/** @{ */ /* Communication channels */ #define WM_OUTPUT_CHANNEL 0x11 #define WM_INPUT_CHANNEL 0x13 @@ -217,8 +220,10 @@ #define SMOOTH_ROLL 0x01 #define SMOOTH_PITCH 0x02 +/** @} */ #include "wiiuse.h" - +/** @addtogroup internal_general */ +/** @{ */ #define _STRINGIFY(s) _STRINGIFY_IMPL(s) #define _STRINGIFY_IMPL(s) #s @@ -238,5 +243,6 @@ int wiiuse_read_data_cb(struct wiimote_t* wm, wiiuse_read_cb read_cb, byte* buff #ifdef __cplusplus } #endif +/** @} */ #endif /* WIIUSE_INTERNAL_H_INCLUDED */