more doxygen cleanup

include/gevent/gevent.h

@@ -37,13 +37,9 @@
 
 #if GFX_USE_GEVENT || defined(__DOXYGEN__)
 
-/**
+/* Data part of a static GListener initializer */
- * @brief   Data part of a static GListener initializer.
- */
 #define _GLISTENER_DATA(name) { _SEMAPHORE_DATA(name.waitqueue, 0), _BSEMAPHORE_DATA(name.eventlock, FALSE), 0, 0, {0} }
-/**
+/* Static GListener initializer */
- * @brief   Static GListener initializer.
- */
 #define GLISTENER_DECL(name) GListener name = _GLISTENER_DATA(name)
 
 /*===========================================================================*/

include/gtimer/gtimer.h

@@ -36,6 +36,7 @@
  *
  * @{
  */
+
 #ifndef _GTIMER_H
 #define _GTIMER_H
 
@@ -47,19 +48,13 @@
 /* Type definitions                                                          */
 /*===========================================================================*/
 
-/**
+/* Data part of a static GTimer initialiser */
- * @brief   Data part of a static GTimer initializer.
- */
 #define _GTIMER_DATA() {0,0,0,0,0,0,0}
 
-/**
+/* Static GTimer initialiser */
- * @brief   Static GTimer initializer.
- */
 #define GTIMER_DECL(name) GTimer name = _GTIMER_DATA()
 
-/**
+/* A callback function (executed in a thread context) */
- * @brief   A callback function (executed in a thread context).
- */
 typedef void (*GTimerFunction)(void *param);
 
 /**
@@ -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

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