From e00f8593e85245a847280dafe10e5a834268557e Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Wed, 19 Dec 2012 19:48:12 +0100 Subject: more doxygen cleanup --- include/gevent/gevent.h | 8 +--- include/gtimer/gtimer.h | 101 +++++++++++++++++++++++++++++++++++++++++++----- 2 files changed, 93 insertions(+), 16 deletions(-) (limited to 'include') diff --git a/include/gevent/gevent.h b/include/gevent/gevent.h index ad386746..67a6185a 100644 --- a/include/gevent/gevent.h +++ b/include/gevent/gevent.h @@ -37,13 +37,9 @@ #if GFX_USE_GEVENT || defined(__DOXYGEN__) -/** - * @brief Data part of a static GListener initializer. - */ +/* Data part of a static GListener initializer */ #define _GLISTENER_DATA(name) { _SEMAPHORE_DATA(name.waitqueue, 0), _BSEMAPHORE_DATA(name.eventlock, FALSE), 0, 0, {0} } -/** - * @brief Static GListener initializer. - */ +/* Static GListener initializer */ #define GLISTENER_DECL(name) GListener name = _GLISTENER_DATA(name) /*===========================================================================*/ diff --git a/include/gtimer/gtimer.h b/include/gtimer/gtimer.h index b286d84e..95ab6ba7 100644 --- a/include/gtimer/gtimer.h +++ b/include/gtimer/gtimer.h @@ -36,6 +36,7 @@ * * @{ */ + #ifndef _GTIMER_H #define _GTIMER_H @@ -47,19 +48,13 @@ /* Type definitions */ /*===========================================================================*/ -/** - * @brief Data part of a static GTimer initializer. - */ +/* Data part of a static GTimer initialiser */ #define _GTIMER_DATA() {0,0,0,0,0,0,0} -/** - * @brief Static GTimer initializer. - */ +/* Static GTimer initialiser */ #define GTIMER_DECL(name) GTimer name = _GTIMER_DATA() -/** - * @brief A callback function (executed in a thread context). - */ +/* A callback function (executed in a thread context) */ typedef void (*GTimerFunction)(void *param); /** @@ -73,7 +68,7 @@ typedef struct GTimer_t { uint16_t flags; struct GTimer_t *next; struct GTimer_t *prev; - } GTimer; +} GTimer; /*===========================================================================*/ /* External declarations. */ @@ -83,11 +78,97 @@ typedef struct GTimer_t { extern "C" { #endif +/** + * @brief Initialise a timer. + * + * @param[in] pt pointer to a GTimer structure + * + * @api + */ void gtimerInit(GTimer *pt); + +/** + * @brief Set a timer going or alter its properties if it is already going. + * + * @param[in] pt Pointer to a GTimer structure + * @param[in] fn The callback function + * @param[in] param The parameter to pass to the callback function + * @param[in] periodic Is the timer a periodic timer? FALSE is a once-only timer. + * @param[in] millisec The timer period. The following special values are allowed: + * TIME_IMMEDIATE causes the callback function to be called asap. + * A periodic timer with this value will fire once only. + * TIME_INFINITE never timeout (unless triggered by gtimerJab or gtimerJabI) + * + * @note If the timer is already active its properties are updated with the new parameters. + * The current period will be immediately canceled (without the callback function being + * called) and the timer will be restart with the new timer properties. + * @note The callback function should be careful not to over-run the thread stack. + * Define a new value for the macro GTIME_THREAD_STACK_SIZE if you want to + * change the default size. + * @note The callback function should return as quickly as possible as all + * timer callbacks are performed by a single thread. If a callback function + * takes too long it could affect the timer response for other timers. + * @note A timer callback function is not a replacement for a dedicated thread if the + * function wants to perform computationally expensive stuff. + * @note As the callback function is called on GTIMER's thread, the function must make sure it uses + * appropriate synchronisation controls such as semaphores or mutexes around any data + * structures it shares with other threads such as the main application thread. + * + * @api + */ void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, systime_t millisec); + +/** + * @brief Stop a timer (periodic or otherwise) + * + * @param[in] pt Pointer to a GTimer structure + * + * @note If the timer is not active this does nothing. + * + * @api + */ void gtimerStop(GTimer *pt); + +/** + * @brief Test if a timer is currently active + * + * @param[in] pt Pointer to a GTimer structure + * + * @return TRUE if active, FALSE otherwise + * + * @api + */ bool_t gtimerIsActive(GTimer *pt); + +/** + * @brief Jab a timer causing the current period to immediate expire + * @details The callback function will be called as soon as possible. + * + * @pre Use from a normal thread context. + * + * @param[in] pt Pointer to a GTimer structure + * + * @note If the timer is not active this does nothing. + * @note Repeated Jabs before the callback function actually happens are ignored. + * + * @api + */ void gtimerJab(GTimer *pt); + +/** + * @brief Jab a timer causing the current period to immediate expire + * @details The callback function will be called as soon as possible. + * + * @pre Use from an interrupt routine context. + * + * @param[in] pt Pointer to a GTimer structure + * + * @note If the timer is not active this does nothing. + * @note Repeated Jabs before the callback function actually happens are ignored. + * + * @iclass + * @api + */ void gtimerJabI(GTimer *pt); #ifdef __cplusplus -- cgit v1.2.3