more doxygen cleanup

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

 /** @} */

+