From ba6988bd893eb08c54ffdb144700530e3a683d6e Mon Sep 17 00:00:00 2001
From: Harald Welte <laforge@gnumonks.org>
Date: Wed, 17 Aug 2011 12:46:48 +0200
Subject: some more doxygen work (include the notion of modules)

---
 src/timer.c | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

(limited to 'src/timer.c')

diff --git a/src/timer.c b/src/timer.c
index bd11a46c..ed2b2963 100644
--- a/src/timer.c
+++ b/src/timer.c
@@ -18,6 +18,13 @@
  *
  */
 
+/*! \addtogroup timer
+ *  @{
+ */
+
+/*! \file timer.c
+ */
+
 #include <assert.h>
 #include <string.h>
 #include <osmocom/core/timer.h>
@@ -31,6 +38,10 @@ static struct timeval s_select_time;
 #define TIME_SMALLER(left, right) \
         (left.tv_sec*MICRO_SECONDS+left.tv_usec) <= (right.tv_sec*MICRO_SECONDS+right.tv_usec)
 
+
+/*! \brief add a new timer to the timer management
+ *  \param[in] timer the timer that should be added
+ */
 void osmo_timer_add(struct osmo_timer_list *timer)
 {
 	struct osmo_timer_list *list_timer;
@@ -47,6 +58,16 @@ void osmo_timer_add(struct osmo_timer_list *timer)
 	llist_add(&timer->entry, &timer_list);
 }
 
+/*! \brief schedule a timer at a given future relative time
+ *  \param[in] timer the to-be-added timer
+ *  \param[in] seconds number of seconds from now
+ *  \param[in] microseconds number of microseconds from now
+ *
+ * This function can be used to (re-)schedule a given timer at a
+ * specified number of seconds+microseconds in the future.  It will
+ * internally add it to the timer management data structures, thus
+ * osmo_timer_add() is automatically called.
+ */
 void
 osmo_timer_schedule(struct osmo_timer_list *timer, int seconds, int microseconds)
 {
@@ -60,6 +81,12 @@ osmo_timer_schedule(struct osmo_timer_list *timer, int seconds, int microseconds
 	osmo_timer_add(timer);
 }
 
+/*! \brief delete a timer from timer management
+ *  \param[in] timer the to-be-deleted timer
+ *
+ * This function can be used to delete a previously added/scheduled
+ * timer from the timer management code.
+ */
 void osmo_timer_del(struct osmo_timer_list *timer)
 {
 	if (timer->in_list) {
@@ -69,6 +96,13 @@ void osmo_timer_del(struct osmo_timer_list *timer)
 	}
 }
 
+/*! \brief check if given timer is still pending
+ *  \param[in] timer the to-be-checked timer
+ *  \return 1 if pending, 0 otherwise
+ *
+ * This function can be used to determine whether a given timer
+ * has alredy expired (returns 0) or is still pending (returns 1)
+ */
 int osmo_timer_pending(struct osmo_timer_list *timer)
 {
 	return timer->active;
@@ -184,3 +218,5 @@ int osmo_timers_check(void)
 	}
 	return i;
 }
+
+/*! }@ */
-- 
cgit v1.2.3