start to add doxygen documentation to libosmocore headers

1 files changed, 43 insertions, 8 deletions

diff --git a/include/osmocom/core/timer.h b/include/osmocom/core/timer.h
index 6c2e8c50..326a0c88 100644
--- a/include/osmocom/core/timer.h
+++ b/include/osmocom/core/timer.h
@@ -18,6 +18,10 @@
  *
  */
 
+/*! \file timer.h
+ *  \brief Osmocom timer handling routines
+ */
+
 #ifndef TIMER_H
 #define TIMER_H
 
@@ -41,27 +45,58 @@
  *        the timers.
  *
  */
+/*! \brief A structure representing a single instance of a timer */
 struct osmo_timer_list {
-	struct llist_head entry;
-	struct timeval timeout;
-	unsigned int active  : 1;
-	unsigned int handled : 1;
-	unsigned int in_list : 1;
+	struct llist_head entry;  /*!< \brief linked list header */
+	struct timeval timeout;   /*!< \brief expiration time */
+	unsigned int active  : 1; /*!< \brief is it active? */
+	unsigned int handled : 1; /*!< \brief did we already handle it */
+	unsigned int in_list : 1; /*!< \brief is it in the global list? */
 
-	void (*cb)(void*);
-	void *data;
+	void (*cb)(void*);	  /*!< \brief call-back called at timeout */
+	void *data;		  /*!< \brief user data for callback */
 };
 
 /**
  * timer management
  */
+
+/*! \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);
+
+/*! \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);
+
+/*! \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);
+
+/*! \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);
 
 
-/**
+/*
  * internal timer list management
  */
 struct timeval *osmo_timers_nearest(void);