core/doc: complete queue.h

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