Merge pull request #1041 from LudwigOrtmann/issue_951

Fix doxygen comments for hwtimer.h, queue.h and io.h

core/include/hwtimer.h

@@ -17,8 +17,8 @@
  * interrupt context and must use the shortest possible execution time (e.g.
  * set a flag and trigger a worker thread).
  *
- * <b>The hardware timer must not be used within applications</b>, use \ref vtimer
+ * <b>The hardware timer should not be used (until you know what
- * instead.
+ * you're doing)<b>, use \ref sys_vtimer instead.
  *
  * @{
  *
@@ -38,8 +38,8 @@
 #include "hwtimer_cpu.h"
 
 /**
- * @def    HWTIMER_SPEED
  * @brief   Number of kernel timer ticks per second
+ * @def     HWTIMER_SPEED
  */
 #ifndef HWTIMER_SPEED
 #warning "HWTIMER_SPEED undefined. Set HWTIMER_SPEED to number of ticks per second for the current architecture."
@@ -60,8 +60,8 @@
 #define HWTIMER_TICKS_TO_US(ticks)        ((ticks) * (1000000L/HWTIMER_SPEED))
 
 /**
- * @def    HWTIMER_MAXTICKS
  * @brief   Maximum hwtimer tick count (before overflow)
+ * @def     HWTIMER_MAXTICKS
  */
 #ifndef HWTIMER_MAXTICKS
 #warning "HWTIMER_MAXTICKS undefined. Set HWTIMER_MAXTICKS to maximum number of ticks countable on the current architecture."
@@ -72,10 +72,12 @@
  */
 #define HWTIMER_OVERFLOW_MICROS()        (1000000L / HWTIMER_SPEED * HWTIMER_MAXTICKS)
 
-typedef uint32_t timer_tick_t;
+typedef uint32_t timer_tick_t; /**< data type for hwtimer ticks */
 
+/**
+ * @brief   initialize the hwtimer module
+ */
 void hwtimer_init(void);
-void hwtimer_init_comp(uint32_t fcpu);
 
 /**
  * @brief   Get the hardware time
@@ -104,7 +106,7 @@ int hwtimer_set_absolute(unsigned long absolute, void (*callback)(void*), void *
 /**
  * @brief Remove a kernel timer
  * @param[in]   t   Id of timer to remove
- * @retval    1 on success
+ * @return      1 on success
  */
 int hwtimer_remove(int t);
 
@@ -114,22 +116,25 @@ int hwtimer_remove(int t);
  */
 void hwtimer_wait(unsigned long ticks);
 
+/**
+ * @brief   determine if the hwtimer module is initialized
+ * @return  1 if the hwtimer module is initialized
+ */
+int hwtimer_active(void);
+
+/**
+ * @brief       initialize hwtimer module data structures and hardware
+ *
+ * @param[in]   fcpu        cpu frequency
+ */
+void hwtimer_init_comp(uint32_t fcpu);
+
 /**
  * @brief       Delay current thread, spinning. Use only in interrupts for VERY short delays!
+ *
  * @param[in]   ticks        Number of kernel ticks to delay
  */
 void hwtimer_spin(unsigned long ticks);
 
-int hwtimer_active(void);
-
-/** @} */
-
-/* internal */
-/**
- * @brief    TODO
- * @internal
- */
-void hwtimer_cpu_init(void (*handler)(int), uint32_t fcpu);
-
 /** @} */
 #endif /* __HWTIMER_H */

core/include/hwtimer_arch.h

@@ -17,6 +17,7 @@
  * @author      Thomas Hillebrandt <hillebra@inf.fu-berlin.de>
  * @author      Heiko Will <hwill@inf.fu-berlin.de>
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
+ * @}
  */
 
 #ifndef HWTIMER_ARCH_H_
@@ -25,40 +26,52 @@
 #include <stdint.h>
 
 /**
- * Initialize architecture dependent kernel timer support.
+ * @brief Initialize architecture dependent kernel timer support.
+ *
+ * @param[in] handler   callback function for the interrupt handler
+ * @param[in] fcpu      cpu frequency
  */
 void hwtimer_arch_init(void (*handler)(int), uint32_t fcpu);
 
 /**
- * Enable interrupts of hardware timers.
+ * @brief Enable interrupts of hardware timers.
  */
 void hwtimer_arch_enable_interrupt(void);
 
 /**
- * Disable interrupts of hardware timers.
+ * @brief Disable interrupts of hardware timers.
  */
 void hwtimer_arch_disable_interrupt(void);
 
 /**
- * Set a kernel timer to raise an interrupt after ::offset kernel timer ticks
+ * @brief Set a kernel timer to raise an interrupt after `offset` kernel timer
- * from now.
+ * ticks from now.
+ *
+ * @param[in] offset    number of ticks
+ * @param[in] timer     hardware timer identifier
  */
 void hwtimer_arch_set(unsigned long offset, short timer);
 
 /**
- * Set a kernel timer to raise an interrupt at specified system time.
+ * @brief Set a kernel timer to raise an interrupt at specified system time.
+ *
+ * @param[in] value     system time
+ * @param[in] timer     hardware timer identifier
  */
 void hwtimer_arch_set_absolute(unsigned long value, short timer);
 
 /**
- * Unset the kernel timer with the given timer ID.
+ * @brief Unset the kernel timer with the given timer ID.
+ *
+ * @param[in] timer     hardware timer identifier
  */
 void hwtimer_arch_unset(short timer);
 
 /**
  * Get the current tick count of the default hardware timer.
+ *
+ * @return  The current tick count of the hardware timer
  */
 unsigned long hwtimer_arch_now(void);
 
-/** @} */
 #endif /* HWTIMER_ARCH_H_ */

core/include/io.h

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2013 Freie Universität Berlin
+ * Copyright (C) 2014 Freie Universität Berlin
  *
  * This file subject to the terms and conditions of the GNU Lesser General
  * Public License. See the file LICENSE in the top level directory for more
@@ -22,6 +22,12 @@
 #ifndef IO_H
 #define IO_H
 
+/**
+ * @brief   Firmware putstring implementation
+ *
+ * @param[in] data  charachters to be written
+ * @param[in] count number of charachters to be written
+ */
 int fw_puts(char *data, int count);
 
 /** @} */

core/include/queue.h

@@ -23,22 +23,79 @@
 #include <stdint.h>
 #include <inttypes.h>
 
-// mspgcc bug : PRIxxx macros not defined before mid-2011 versions
+/* mspgcc bug : PRIxxx macros not defined before mid-2011 versions */
+/**
+ * @brief   Macro for printing 32 bit format specifier
+ * @def     PRIu32
+ */
 #ifndef PRIu32
 #define PRIu32 "lu"
 #endif
 
+/**
+ * data type for queue nodes
+ */
 typedef struct queue_node_t {
-    struct queue_node_t *next;
+    struct queue_node_t *next;  /**< next queue node */
-    unsigned int data;
+    unsigned int data;          /**< queue node data */
-    uint32_t priority;
+    uint32_t priority;          /**< queue node priority */
 } queue_node_t;
 
+/**
+ * @brief attach `new_obj` to the tail of the queue (identified
+ * `root`)
+ *
+ * @param[in,out]   root    the queue's root
+ * @param[in]       new_obj the object to append
+ */
 void queue_add_tail(queue_node_t *root, queue_node_t *new_obj);
+
+/**
+ * @brief attach `new_obj` to `root` at the beginning
+ *
+ * @param[in,out]   root    the queue's root
+ * @param[in]       new_obj the object to prepend
+ */
 void queue_add_head(queue_node_t *root, queue_node_t *new_obj);
+
+/**
+ * @brief remove the queue's head
+ *
+ * @param[out]  root    the queue's root
+ *
+ * @return              the old head
+ */
 queue_node_t *queue_remove_head(queue_node_t *root);
+
+/**
+ * @brief insert `new_obj` into `root` based on its priority
+ *
+ * @details
+ * The new object will be appended after objects with the same priority.
+ *
+ * @param[in,out]   root    the queue's root
+ * @param[in]       new_obj the object to prepend
+ */
 void queue_priority_add(queue_node_t *root, queue_node_t *new_obj);
+
+/**
+ * @brief insert `new_obj` into `root` based on an arbitrary priority
+ *
+ * @details
+ * The new object will be appended after objects with the same priority.
+ *
+ * @param[in,out]   root    the queue's root
+ * @param[in]       new_obj the object to prepend
+ * @param[in]       cmp     a comparator function used to determine the priority
+ */
 void queue_priority_add_generic(queue_node_t *root, queue_node_t *new_obj, int(*cmp)(queue_node_t *, queue_node_t *)) ;
+
+/**
+ * @brief remove `node` from `root`
+ *
+ * @param[in,out]   root    the queue's root
+ * @param[in]       node    the node to remove
+ */
 void queue_remove(queue_node_t *root, queue_node_t *node);
 
 #if ENABLE_DEBUG