From e00f8593e85245a847280dafe10e5a834268557e Mon Sep 17 00:00:00 2001 From: Joel Bodenmann Date: Wed, 19 Dec 2012 19:48:12 +0100 Subject: [PATCH] more doxygen cleanup --- include/gevent/gevent.h | 8 +--- include/gtimer/gtimer.h | 101 ++++++++++++++++++++++++++++++++++++---- src/gtimer/gtimer.c | 84 +-------------------------------- 3 files changed, 95 insertions(+), 98 deletions(-) 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 diff --git a/src/gtimer/gtimer.c b/src/gtimer/gtimer.c index 76c527f4..76dd57e2 100644 --- a/src/gtimer/gtimer.c +++ b/src/gtimer/gtimer.c @@ -43,7 +43,7 @@ /* Don't rework this macro to use a ternary operator - the gcc compiler stuffs it up */ #define TimeIsWithin(x, start, end) ((end >= start && x >= start && x <= end) || (end < start && (x >= start || x <= end))) -// This mutex protects access to our tables +/* This mutex protects access to our tables */ static MUTEX_DECL(mutex); static Thread *pThread = 0; static GTimer *pTimerHead = 0; @@ -141,46 +141,10 @@ static msg_t GTimerThreadHandler(void *arg) { return 0; } -/** - * @brief Initialise a timer. - * - * @param[in] pt pointer to a GTimer structure - * - * @api - */ void gtimerInit(GTimer *pt) { pt->flags = 0; } -/** - * @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) { chMtxLock(&mutex); @@ -230,15 +194,6 @@ void gtimerStart(GTimer *pt, GTimerFunction fn, void *param, bool_t periodic, sy chMtxUnlock(); } -/** - * @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) { chMtxLock(&mutex); if (pt->flags & GTIMER_FLG_SCHEDULED) { @@ -257,32 +212,10 @@ void gtimerStop(GTimer *pt) { chMtxUnlock(); } -/** - * @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) { return (pt->flags & GTIMER_FLG_SCHEDULED) ? TRUE : FALSE; } -/** - * @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) { chMtxLock(&mutex); @@ -294,20 +227,6 @@ void gtimerJab(GTimer *pt) { chMtxUnlock(); } -/** - * @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) { // Jab it! pt->flags |= GTIMER_FLG_JABBED; @@ -318,3 +237,4 @@ void gtimerJabI(GTimer *pt) { #endif /* GFX_USE_GTIMER */ /** @} */ +