core: improved doxygen documentation

improved files complient to issue #950
- thread.h
- flags.h
- debug.h
- crash.h

core/include/crash.h

@@ -14,7 +14,7 @@
  * @brief       Crash handling header
  *
  * Define a core_panic() function that allows to stop/reboot the system
- *  when an unrecoverable problem has occured.
+ * when an unrecoverable problem has occurred.
  *
  * @author      Kévin Roussel <Kevin.Roussel@inria.fr>
  */
@@ -24,18 +24,27 @@
 
 #include "kernel.h"
 
-/** Handle an unrecoverable error by halting or rebooting the system.
-    A numeric code indicating the failure reason can be given
-    as the ::crash_code parameter.
-    Detailing the failure is possible using the ::message parameter.
-    This function should serve a similar purpose as the panic()
-    function of Unix/Linux kernels.
-
-    If the DEVELHELP macro is defined, the system will be halted;
-    the system will be rebooted otherwise.
-
-    WARNING: this function NEVER returns! */
+/**
+ * @brief Handle an unrecoverable error by halting or rebooting the system
+ *
+ * A numeric code indicating the failure reason can be given
+ * as the *crash_code* parameter.
+ *
+ * Detailing the failure is possible using the *message* parameter.
+ * This function should serve a similar purpose as the panic()
+ * function of Unix/Linux kernels.
+ *
+ * If the DEVELHELP macro is defined, the system will be halted;
+ * the system will be rebooted otherwise.
+ *
+ * @warning this function NEVER returns!
+ *
+ * @param[in] crash_code    a unique code for identifying the crash reason
+ * @param[in] message       a human readable reason for the crash
+ *
+ * @return                  this function never returns
+ * */
 NORETURN void core_panic(int crash_code, const char *message);
 
-/** @} */
 #endif /* __CRASH_H */
+/** @} */

core/include/debug.h

 /*
- * Copyright (C) 2013 Freie Universität Berlin
+ * Copyright (C) 2014 Freie Universität Berlin
  *
  * This file is subject to the terms and conditions of the GNU Lesser General
  * Public License. See the file LICENSE in the top level directory for more
@@ -25,6 +25,16 @@
 #include <stdio.h>
 #include "sched.h"
 
+/**
+ * @name Print debug information if the calling thread stack is large enough
+ *
+ * Use this macro the same as printf. When DEVHELP is defined inside an
+ * implementation file, all usages of *DEBUG_PRINTF* will print the given
+ * information to std-out. If DEVHELP is not set, all occurrences of
+ * *DEBUG_PRINTF* will be ignored.
+ *
+ * @{
+ */
 #if DEVELHELP
 #include "cpu-conf.h"
 #define DEBUG_PRINT(...) \
@@ -39,7 +49,21 @@
 #else
 #define DEBUG_PRINT(...) printf(__VA_ARGS__)
 #endif
+/** @} */
 
+/**
+ * @brief Print debug information to std-out
+ *
+ * If *ENABLE_DEBUG* is defined inside an implementation file, all calls to
+ * *DEBUG* and *DEBUGF* will work the same as *printf* and output the given
+ * information to stdout. If *ENABLE_DEBUG* is not defined, all calls to
+ * *DEBUG* and *DEBUGF* will be ignored.
+ *
+ * In addition to just printing the given information *DEBUGF* will further
+ * print extended debug information about the current thread and function.
+ *
+ * @{
+ */
 #if ENABLE_DEBUG
 #include "tcb.h"
 #define DEBUG(...) DEBUG_PRINT(__VA_ARGS__)
@@ -55,6 +79,7 @@
 #define DEBUG(...)
 #define DEBUGF(...)
 #endif
-
 /** @} */
+
 #endif /* __DEBUG_H */
+/** @} */

core/include/flags.h

 /*
- * Copyright (C) 2013 Freie Universität Berlin
+ * Copyright (C) 2014 Freie Universität Berlin
  *
  * This file is subject to the terms and conditions of the GNU Lesser General
  * Public License. See the file LICENSE in the top level directory for more
@@ -19,10 +19,16 @@
 #ifndef _FLAGS_H
 #define _FLAGS_H
 
-#define CREATE_SLEEPING     (1)
-#define AUTO_FREE           (2)
-#define CREATE_WOUT_YIELD   (4)
-#define CREATE_STACKTEST    (8)
+/**
+ * @name Optional flags for controlling a threads initial state.
+ * @{
+ */
+#define CREATE_SLEEPING     (1)     /**< set the new thread to sleeping */
+#define AUTO_FREE           (2)     /**< currently not implemented */
+#define CREATE_WOUT_YIELD   (4)     /**< do not automatically call thread_yield() after creation */
+#define CREATE_STACKTEST    (8)     /**< write markers into the thread's stack to measure stack
+                                         usage (for debugging) */
+/** @} */
 
+#endif /* _FLAGS_H */
 /** @} */
-#endif // _FLAGS_H

core/include/thread.h

 /*
- * 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
@@ -29,77 +29,122 @@
 
 #define STATUS_NOT_FOUND (-1)
 
-/** Minimum stack size */
+/**
+ * @name Minimum stack size
+ */
 #ifndef MINIMUM_STACK_SIZE
 #define MINIMUM_STACK_SIZE  (sizeof(tcb_t))
 #endif
 
 /**
- * @brief Creates a new thread.
+ * @brief Creates a new thread
+ *
+ * Creating a new thread is done in two steps:
+ * 1. the new thread's stack is initialized depending on the platform
+ * 2. the new thread is added to the scheduler to be run
+ *
+ * As RIOT is using a fixed priority scheduling algorithm, threads
+ * are scheduled base on their priority. The priority is fixed for every thread
+ * and specified during the threads creation by the *priority* parameter.
+ *
+ * A low value for *priority* number means the thread having a high priority
+ * with 0 being the highest possible priority.
  *
- * @param   stack Lowest address of preallocated stack space
- * @param   stacksize
- * @param   flags Options:
- * YIELD: force context switch.
- * CREATE_SLEEPING: set new thread to sleeping state, thread must be woken up manually.
- * CREATE_STACKTEST: initialize stack with values needed for stack overflow testing.
+ * The lowest possible priority is *PRIORITY_IDLE - 1*. The value is depending
+ * on the platforms architecture, e.g. 30 in 32-bit systems, 14 in 16-bit systems.
  *
- * @param priority Priority of newly created thread. Lower number means higher
- * priority. 0 means highest possible priority. Lowest priority is
- * PRIORITY_IDLE-1, usually 30.
  *
- * @return  returns <0 on error, pid of newly created task else.
+ * In addition to the priority, the *flags* argument can be used to alter the
+ * newly created threads behavior after creation. The following flags are available:
+ *  - CREATE_SLEEPING       the newly created thread will be put to sleeping state and
+ *                          must be waken up manually
+ *  - CREATE_WOUT_YIELD     the newly created thread will not run immediately after creation
+ *  - CREATE_STACKTEST      write markers into the thread's stack to measure the stack's memory
+ *                          usage (for debugging and profiling purposes)
+ *
+ * @param[out] stack    start address of the preallocated stack memory
+ * @param[in] stacksize the size of the thread's stack in bytes
+ * @param[in] priority  priority of the new thread, lower mean higher priority
+ * @param[in] flags     optional flags for the creation of the new thread
+ * @param[in] function  pointer to the code that is executed in the new thread
+ * @param[in] name      a human readable descriptor for the thread
+ *
+ * @return              value ``<0`` on error
+ * @return              pid of newly created task, otherwise
 */
-int thread_create(char *stack, int stacksize, char priority, int flags, void (*function) (void), const char *name);
+int thread_create(char *stack,
+                  int stacksize,
+                  char priority,
+                  int flags,
+                  void (*function) (void),
+                  const char *name);
 
 /**
- * @brief   returns the status of a process.
- * @return  STATUS_NOT_FOUND if pid is unknown
+ * @brief Returns the status of a process
+ *
+ * @param[in] pid   the PID of the thread to get the status from
+ *
+ * @return          status of the thread
+ * @return          `STATUS_NOT_FOUND` if pid is unknown
  */
 int thread_getstatus(int pid);
 
 /**
- * @brief   returns the name of a process.
- * @return  NULL if pid is unknown
+ * @brief Returns the name of a process
+ *
+ * @param[in] pid   the PID of the thread to get the name from
+ *
+ * @return          the threads name
+ * @return          `NULL` if pid is unknown
  */
 const char *thread_getname(int pid);
 
 /**
- * @brief   Puts the current thread into sleep mode. Has to be woken up externally.
+ * @brief Puts the current thread into sleep mode. Has to be woken up externally.
  */
 void thread_sleep(void);
 
 /**
- * @brief   The current thread yields and let the scheduler run.
+ * @brief The current thread yields and let the scheduler run
+ *
+ * The current thread will resume operation immediately if there is no other thread with the same
+ * or a higher priority.
  */
 void thread_yield(void);
 
 /**
- * @brief   Wakes up a sleeping thread.
- * @param   pid The PID of the thread to be woken up
- * @return  STATUS_NOT_FOUND if pid is unknown or not sleeping
+ * @brief Wakes up a sleeping thread.
+ *
+ * @param[in] pid   the PID of the thread to be woken up
+ *
+ * @return          `1` on success
+ * @return          `STATUS_NOT_FOUND` if pid is unknown or not sleeping
  */
 int thread_wakeup(int pid);
 
 
 /**
- * @brief   Returns the process ID of the currently running thread.
- * @return  Obviously you are not a golfer.
+ * @brief Returns the process ID of the currently running thread
+ *
+ * @return          obviously you are not a golfer.
  */
 int thread_getpid(void);
 
 /**
- * @brief   Returns the process ID of the thread running before the current one.
- * @return  Obviously you are not a golfer.
+ * @brief Returns the process ID of the thread running before the current one
+ *
+ * @return          obviously you are not a golfer.
  */
 int thread_getlastpid(void);
 
 /**
- * @brief Measures the stack usage of a stack.
+ * @brief Measures the stack usage of a stack
+ *
  * Only works if the thread was created with the flag CREATE_STACKTEST.
  *
- * @param stack The stack you want to measure. try active_thread->stack_start.
- * @return  The amount of unused space of the thread's stack
+ * @param[in] stack the stack you want to measure. try `active_thread->stack_start`
+ *
+ * @return          the amount of unused space of the thread's stack
  */
 int thread_measure_stack_free(char *stack);