more doxygen cleanup

2 files changed, 93 insertions, 16 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