Merge pull request #955 from thomaseichinger/fix_doc

core: documentation: fix doxygen documentation in cib.h clist.h config.h tcb.h

core/include/cib.h

@@ -12,22 +12,61 @@
  *
  * @file        cib.h
  * @brief       Circular integer buffer interface
+ * @details     This structure provides an organizational interface
+ *              and combined with an memory array forms a circular buffer.
  *
+ * @author      unknown, propably Kaspar Schleiser <kaspar@schleiser.de>
  */
 
 #ifndef __CIB_H
 #define __CIB_H
 
+/**
+ * @brief circular integer buffer structure
+ */
 typedef struct cib_t {
-    unsigned int read_count;
-    unsigned int write_count;
-    unsigned int complement;
+    unsigned int read_count;    /**< count read accesses  */
+    unsigned int write_count;   /**< count write accesses */
+    unsigned int complement;    /**< hold complement      */
 } cib_t;
 
+/**
+ * @brief Initialize cib_t to 0 and set size.
+ *
+ * @param[out] cib      Buffer to initialize.
+ *                      Must not be NULL.
+ * @param[in]  size     Size of the buffer.
+ */
 void cib_init(cib_t *cib, unsigned int size);
+
+/**
+ * @brief Get the index of the next item in buffer.
+ *
+ * @param[in,out] cib   corresponding *cib* to buffer.
+ *                      Must not be NULL.
+ * @return index of next item, -1 on error.
+ */
 int cib_get(cib_t *cib);
+
+/**
+ * @brief Get index for item in buffer to put to.
+ *
+ * @param[in,out] cib   corresponding *cib* to buffer.
+ *                      Must not be NULL.
+ * @return index of item to put to, -1 on error.
+ */
 int cib_put(cib_t *cib);
+
+/**
+ * @brief Calculates difference between cib_put() and cib_get() accesses.
+ *
+ * @param[in] cib       the cib_t to check.
+ *                      Must not be NULL.
+ * @return Negative number for #cib_get > #cib_put
+ * @return 0 for #cib_get == #cib_put
+ * @return positive number for #cib_get < #cib_put
+ */
 int cib_avail(cib_t *cib);
 
-/** @} */
 #endif /* __CIB_H */
+/** @} */

core/include/clist.h

@@ -11,7 +11,7 @@
  * @{
  *
  * @file        clist.h
- * @brief       Circular linkes list
+ * @brief       Circular linked list
  *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
@@ -20,29 +20,55 @@
 #ifndef __CLIST_H
 #define __CLIST_H
 
+/**
+ * @brief Structure representing a node in the clist.
+ */
 typedef struct clist_node_t {
-    struct clist_node_t *next;
-    struct clist_node_t *prev;
-    unsigned int data;
+    struct clist_node_t *next;  /**< pointer to next node         */
+    struct clist_node_t *prev;  /**< pointer to the previous node */
+    unsigned int data;          /**< holding data for this node   */
 } clist_node_t;
 
-/* inserts new_node after node */
+/**
+ * @brief Inserts *new_node* after *node* into list
+ *
+ * @param[in,out]   node        Node after which *new_node* gets inserted
+ * @param[in,out]   new_node    Node which gets inserted after *node*.
+ *                              Must not be NULL.
+ */
 void clist_add(clist_node_t **node, clist_node_t *new_node);
 
-/* removes node. */
+/**
+ * @brief Removes *node* from list
+ *
+ * @param[in,out]   list        Pointer to the *list* to remove *node* from.
+ * @param[in]       node        Node to remove from *list*
+ *                              Must not be NULL.
+ */
 void clist_remove(clist_node_t **list, clist_node_t *node);
 
-/* advances the circle list. second list entry will be first, first is last. */
-/*void clist_advance(clist_node_t** list);*/
-
+/**
+ * @brief Advances the circle list.
+ * 
+ * The result of this function is will be a list with
+ * nodes shifted by one. So second list entry will be
+ * first, first is last.
+ *
+ * @param[in,out]   list        The list to work upon.
+ */
 static inline void clist_advance(clist_node_t **list)
 {
     *list = (*list)->next;
 }
 
 #if ENABLE_DEBUG
+/**
+ * @brief Prints list to stdout.
+ *
+ * @param[in]       clist       The list to get printed out.
+ */
 void clist_print(clist_node_t *clist);
 #endif
 
+#endif /* __CLIST_H */
 /** @} */
-#endif // __CLIST_H

core/include/config.h

@@ -21,40 +21,50 @@
 
 #include <stdint.h>
 
-#define CONFIG_KEY      (0x1701)
-#define CONFIG_NAME_LEN (10)
+#define CONFIG_KEY      (0x1701)    /**< key to identify configuration             */
+#define CONFIG_NAME_LEN (10)        /**< length of name for configuration in bytes */
 
+/**
+ * @brief Memory for configuration defined externally.
+ */
 extern char configmem[];
 
-/* @brief:  Stores configuration data of the node */
+/**
+ * @brief  Stores configuration data of the node.
+ */
 typedef struct {
-    uint16_t id;                ///< unique node identifier
-    uint8_t radio_address;      ///< address for radio communication
-    uint8_t radio_channel;      ///< current frequency
-    char name[CONFIG_NAME_LEN]; ///< name of the node
+    uint16_t id;                /**< unique node identifier          */
+    uint8_t radio_address;      /**< address for radio communication */
+    uint8_t radio_channel;      /**< current frequency               */
+    char name[CONFIG_NAME_LEN]; /**< name of the node                */
 } config_t;
 
-/* @brief:  Element to store in flashrom */
+/**
+ * @brief  Element to store in flashrom.
+ */
 typedef struct {
-    uint16_t magic_key;         ///< validity check
-    config_t config;            ///< the node's configuration
+    uint16_t magic_key;         /**< validity check           */
+    config_t config;            /**< the node's configuration */
 } configmem_t;
 
+/**
+ * @brief Variable sysconfig defined externally
+ */
 extern config_t sysconfig;
 
 /**
- * @brief:  Write configuration back to flashrom
+ * @brief  Write configuration back to flashrom.
  *
  * @return 1 on success, 0 otherwise
  */
 uint8_t config_save(void);
 
 /**
- * @brief: Read configuration from flashrom and stores it to sysconfig
+ * @brief Read configuration from flashrom and stores it to sysconfig
  *
- * @note: If no configuration is present within flashrom a new configuration will be created
+ * @note If no configuration is present within flashrom a new configuration will be created
  */
 void config_load(void);
 
-/** @} */
 #endif /* CONFIG_H */
+/** @} */

core/include/tcb.h

@@ -27,44 +27,55 @@
 #include "cib.h"
 #include "msg.h"
 
-/* thread status list */
-/* blocked states: */
-#define STATUS_STOPPED          0                      /**< has terminated */
-#define STATUS_SLEEPING         1                      /**< sleeping */
-#define STATUS_MUTEX_BLOCKED    2                      /**< waiting for a locked mutex */
-#define STATUS_RECEIVE_BLOCKED  3                      /**< waiting for a message */
-#define STATUS_SEND_BLOCKED     4                      /**< waiting for message to be
-                                                           *  delivered */
-#define STATUS_REPLY_BLOCKED    5                      /**< waiting for a message response */
-#define STATUS_TIMER_WAITING    6                      /**< waiting for a timer to fire */
-
-#define STATUS_ON_RUNQUEUE      7                      /**< */
-
-/* these have to be on a run queue: */
-#define STATUS_RUNNING          7                      /**< currently running */
-#define STATUS_PENDING          8                      /**< waiting to be scheduled to run */
-
+/**
+ * @brief Thread status list
+ * @{
+ */
+/**
+ * @brief Blocked states.
+ * @{
+ */
+#define STATUS_STOPPED          0               /**< has terminated                     */
+#define STATUS_SLEEPING         1               /**< sleeping                           */
+#define STATUS_MUTEX_BLOCKED    2               /**< waiting for a locked mutex         */
+#define STATUS_RECEIVE_BLOCKED  3               /**< waiting for a message              */
+#define STATUS_SEND_BLOCKED     4               /**< waiting for message to be delivered*/
+#define STATUS_REPLY_BLOCKED    5               /**< waiting for a message response     */
+#define STATUS_TIMER_WAITING    6               /**< waiting for a timer to fire        */
+/** @} */
 
+/**
+ * @brief These have to be on a run queue.
+ * @{*/
+#define STATUS_ON_RUNQUEUE      7               /**< to check if on run queue 
+                                                 `st >= STATUS_ON_RUNQUEUE`             */
+#define STATUS_RUNNING          7               /**< currently running                  */
+#define STATUS_PENDING          8               /**< waiting to be scheduled to run     */
+/** @} */
+/** @} */
 
+/**
+ * @brief @c tcb_t holds thread's context data.
+ */
 typedef struct tcb_t {
-    char *sp;
-    uint16_t status;
+    char *sp;                   /**< thread's stack pointer         */
+    uint16_t status;            /**< thread's status                */
 
-    uint16_t pid;
-    uint16_t priority;
+    uint16_t pid;               /**< thread's process id            */
+    uint16_t priority;          /**< thread's priority              */
 
-    clist_node_t rq_entry;
+    clist_node_t rq_entry;      /**< run queue entry                */
 
-    void *wait_data;
-    queue_node_t msg_waiters;
+    void *wait_data;            /**< holding messages               */
+    queue_node_t msg_waiters;   /**< threads waiting on message     */
 
-    cib_t msg_queue;
-    msg_t *msg_array;
+    cib_t msg_queue;            /**< message queue                  */
+    msg_t *msg_array;           /**< memory holding messages        */
 
-    const char *name;
-    char *stack_start;
-    int stack_size;
+    const char *name;           /**< thread's name                  */
+    char *stack_start;          /**< thread's stack start address   */
+    int stack_size;             /**< thread's stack size            */
 } tcb_t;
 
-/** @} */
 #endif /* TCB_H_ */
+/** @} */