Fixed doxygen comments, focused on file headers and group definitions

core/bitarithm.c

@@ -1,17 +1,22 @@
-/**
- * bit arithmetic helper functions
- *
+/*
  * Copyright (C) 2013 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
  * details.
+ */
+ 
+/**
+ * @ingroup     core_util
+ * @{
+ *
+ * @file        bitarithm.c
+ * @brief       Bit arithmetic helper functions implementation
+ *
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
+ * @author      Martin Lenders <mlenders@inf.fu-berlin.de>
  *
- * \ingroup bitarithm
- * \{
- * \file
- * \author Kaspar Schleiser <kaspar@schleiser.de>
- * \}
+ * @}
  */
 
 #include <stdio.h>

core/cib.c

@@ -1,3 +1,21 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+ 
+ /**
+ * @ingroup     core_util
+ * @{
+ *
+ * @file        cib.c
+ * @brief       Circular integer buffer implementation
+ *
+ * @}
+ */
+
 #include <cib.h>
 
 void cib_init(cib_t *cib, unsigned int size)

core/clist.c

@@ -1,16 +1,20 @@
-/**
- * simple circular linked list
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup kernel
+ */
+ 
+/**
+ * @ingroup     core_util
  * @{
- * @file
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        clist.c
+ * @brief       Circular linked list implementation
+ *
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
+ *
  * @}
  */
 

core/doc.txt

@@ -0,0 +1,27 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
+/**
+ * @defgroup core Kernel
+ * @brief The RIOT micro-kernel containing the core functionality
+ * 
+ * The kernel module contains only the basic OS functionality such as the sheduler, threading, synchronization
+ * and IRQ-handling. The only exception is the integration of the hardware timer into this module.
+ */
+ 
+/**
+ * @defgroup    core_util Kernel utilities
+ * @ingroup     core
+ * @brief       Utilies and data structures used by the kernel
+ */
+ 
+/**
+ * @defgroup    core_internal Startup and Configuration
+ * @ingroup     core
+ * @brief       Configuration data and startup code for the kernel
+ */

core/hwtimer.c

@@ -1,19 +1,23 @@
-/**
- * hardware timer abstraction
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup kernel
+ */
+ 
+/**
+ * @ingroup     core_hwtimer
  * @{
- * @file
+ *
+ * @file        hwtimer.c
+ * @brief       Hardware timer abstraction implementation
+ *
  * @author      Heiko Will <hwill@inf.fu-berlin.de>
  * @author      Thomas Hillebrandt <hillebra@inf.fu-berlin.de>
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  * @author      Oliver Hahm <oliver.hahm@fu-berlin.de>
+ *
  * @}
  */
 

core/include/atomic.h

@@ -1,17 +1,20 @@
-/**
- * atomic function declarations
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup	kernel
+ */
+ 
+/**
+ * @addtogroup  core_util
  * @{
- * @file
- * @author Freie Universität Berlin, Computer Systems & Telematics
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        atomic.h
+ * @brief       Atomic function declarations
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
  */
 
 #ifndef _ATOMIC_H
@@ -23,7 +26,5 @@
 
 extern unsigned int atomic_set_return(unsigned int *val, unsigned int set);
 
-/**
- * @}
- */
+/** @} */
 #endif /* _ATOMIC_H */

core/include/bitarithm.h

@@ -1,30 +1,33 @@
-/**
- * Helper functions for bit arithmetic
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @defgroup bitarithm Bit Arithmetic
- * @ingroup	lib
+ */
+
+/** 
+ * @addtogroup  core_util
  * @{
- * @file
- * @author Freie Universität Berlin, Computer Systems & Telematics
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        bitarithm.h
+ * @brief       Helper functions for bit arithmetic
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
+ * @author      Martin Lenders <mlenders@inf.fu-berlin.de>
  */
 
 #ifndef BITARITHM_H_
 #define BITARITHM_H_
 
-#define BS(val, bit)		((val) & (bit))
-#define BS_COND(condition, target, mask)		(target) ^= ( (-(condition) ^ (target)) & (mask) )
-#define SETBIT(val, bit)	val |= (bit)
-#define CLRBIT(val, bit)	val &= (~(bit))
+#define BS(val, bit)        ((val) & (bit))
+#define BS_COND(condition, target, mask)        (target) ^= ( (-(condition) ^ (target)) & (mask) )
+#define SETBIT(val, bit)    val |= (bit)
+#define CLRBIT(val, bit)    val &= (~(bit))
 
 /**
- * @name	Single Bit Defines
+ * @name    Single Bit Defines
  * @{
  */
 #ifndef BIT0
@@ -68,35 +71,32 @@
 #define ARCH_32_BIT   (__INT_MAX__ == 2147483647)
 
 /**
- * @brief	Returns the number of the highest '1' bit in a value
- * @param[in]	v	Input value
- * @return			Bit Number
+ * @brief   Returns the number of the highest '1' bit in a value
+ * @param[in]   v   Input value
+ * @return          Bit Number
  *
  * Source: http://graphics.stanford.edu/~seander/bithacks.html#IntegerLogObvious
  */
 unsigned number_of_highest_bit(unsigned v);
 
 /**
- * @brief	Returns the number of the lowest '1' bit in a value
- * @param[in]	v	Input value - must be unequal to '0', otherwise the
+ * @brief   Returns the number of the lowest '1' bit in a value
+ * @param[in]   v   Input value - must be unequal to '0', otherwise the
  *                  function will produce an infinite loop
- * @return			Bit Number
+ * @return          Bit Number
  *
  * Source: http://graphics.stanford.edu/~seander/bithacks.html#IntegerLogObvious
  */
 unsigned number_of_lowest_bit(register unsigned v);
 
 /**
- * @brief	Returns the number of bits set in a value
- * @param[in]	v	Input value
- * @return			Number of set bits
+ * @brief   Returns the number of bits set in a value
+ * @param[in]   v   Input value
+ * @return          Number of set bits
  *
  * Source: http://graphics.stanford.edu/~seander/bithacks.html#IntegerLogObvious
  */
 unsigned number_of_bits_set(unsigned v);
 
-/**
- * @}
- */
-
+/** @} */
 #endif /* BITARITHM_H_ */

core/include/cib.h

@@ -1,3 +1,20 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+ 
+ /**
+ * @addtogroup  core_util
+ * @{
+ *
+ * @file        cib.h
+ * @brief       Circular integer buffer interface
+ *
+ */
+
 #ifndef __CIB_H
 #define __CIB_H
 
@@ -12,4 +29,5 @@ int cib_get(cib_t *cib);
 int cib_put(cib_t *cib);
 int cib_avail(cib_t *cib);
 
+/** @} */
 #endif /* __CIB_H */

core/include/clist.h

@@ -1,19 +1,20 @@
-/**
- * Circular linked list implementation
- *
- * Used by the scheduler
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup	lib
+ */
+
+/**
+ * @addtogroup  core_util
  * @{
- * @file
- * @author Freie Universität Berlin, Computer Systems & Telematics
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        clist.h
+ * @brief       Circular linkes list
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
  */
 
 #ifndef __CLIST_H
@@ -43,8 +44,6 @@ static inline void clist_advance(clist_node_t **list)
 void clist_print(clist_node_t *clist);
 #endif
 
-/**
- * @}
- */
+/** @} */
 #endif // __CLIST_H
 

core/include/config.h

@@ -1,3 +1,21 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
+/**
+ * @addtogroup  core_internal
+ * @{
+ *
+ * @file        config.h
+ * @brief       Kernel configuration interface
+ *
+ */
+
+
 #ifndef CONFIG_H
 #define CONFIG_H
 
@@ -36,4 +54,5 @@ uint8_t config_save(void);
  */
 void config_load(void);
 
+/** @} */
 #endif /* CONFIG_H */

core/include/debug.h

@@ -1,23 +1,27 @@
-/**
- * Debug-Header.
- *
- * #define ENABLE_DEBUG, include this and then use DEBUG as printf you can toggle.
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup	kernel
+ */
+ 
+/**
+ * @addtogroup  core_util
  * @{
- * @file
- * @author Freie Universität Berlin, Computer Systems & Telematics
- * @author Kaspar Schleiser <kaspar@schleiser.de>
- * @}
+ *
+ * @file        debug.h
+ * @brief       Debug-header
+ *
+ * #define ENABLE_DEBUG, include this and then use DEBUG as printf you can toggle.
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
  */
-
-
+ 
+#ifndef __DEBUG_H
+#define __DEBUG_H
+ 
 #include <stdio.h>
 
 #if ENABLE_DEBUG
@@ -27,3 +31,5 @@
 #define DEBUG(...)
 #endif
 
+/** @} */
+#endif /* __DEBUG_H */

core/include/flags.h

@@ -1,28 +1,28 @@
-/**
- * (misc flag definitions)
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup	kernel
+ */
+
+/**
+ * @addtogroup  core_internal
  * @{
- * @file
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        flags.h
+ * @brief       Misc flag definitions
+ *
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
  */
 
 #ifndef _FLAGS_H
 #define _FLAGS_H
 
-#define CREATE_SLEEPING 	(1)
-#define AUTO_FREE 	        (2)
-#define CREATE_WOUT_YIELD 	(4)
-#define CREATE_STACKTEST 	(8)
+#define CREATE_SLEEPING     (1)
+#define AUTO_FREE           (2)
+#define CREATE_WOUT_YIELD   (4)
+#define CREATE_STACKTEST    (8)
 
-/**
- * @}
- */
+/** @} */
 #endif // _FLAGS_H
-

core/include/hwtimer.h

@@ -1,5 +1,15 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
 /**
- * Hardware timer interface
+ * @defgroup    core_hwtimer Hardware timer
+ * @ingroup     core
+ * @brief       Hardware timer interface
  *
  * The Hardware timers are directly mapped to hardware timers with minimum
  * latency. They are intended for short intervals and to be used in time
@@ -7,24 +17,18 @@
  * interrupt context and must use the shortest possible execution time (e.g.
  * set a flag and trigger a worker thread).
  *
- * <b>hwtimer must not be used within applications</b>, use \ref vtimer
+ * <b>The hardware timer must not be used within applications</b>, use \ref vtimer
  * instead.
  *
- * @defgroup hwtimer    Hardware timer
- * @ingroup kernel
  * @{
- * @file
  *
- * @author Freie Universität Berlin, Computer Systems & Telematics
- * @author Heiko Will
- * @author Kaspar Schleiser <kaspar@schleiser.de>
- * @author Michael Baar
+ * @file        hwtimer.h
+ * @brief       HW-timer abstraction
  *
- * Copyright (C) 2013 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
- * details.
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Heiko Will
+ * @author      Kaspar Schleiser <kaspar@schleiser.de>
+ * @author      Michael Baar
  */
 
 #ifndef __HWTIMER_H
@@ -118,6 +122,10 @@ void hwtimer_spin(unsigned long ticks);
 
 int hwtimer_active(void);
 
+/**
+ * @}
+ */
+
 /* internal */
 
 /**

core/include/hwtimer_arch.h

@@ -1,20 +1,24 @@
-/**
- * Hardware timer abstraction
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup	kernel
+ */
+ 
+/**
+ * @addtogroup  core_hwtimer
  * @{
- * @file
- * @author Freie Universität Berlin, Computer Systems & Telematics
- * @author Thomas Hillebrandt <hillebra@inf.fu-berlin.de>
- * @author Heiko Will <hwill@inf.fu-berlin.de>
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        hwtimer_arch.h
+ * @brief       Architecture specific hwtimer API
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Thomas Hillebrandt <hillebra@inf.fu-berlin.de>
+ * @author      Heiko Will <hwill@inf.fu-berlin.de>
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
  */
+ 
 #ifndef HWTIMER_ARCH_H_
 #define HWTIMER_ARCH_H_
 
@@ -56,7 +60,5 @@ void hwtimer_arch_unset(short timer);
  */
 unsigned long hwtimer_arch_now(void);
 
-/**
- * @}
- */
+/** @} */
 #endif /* HWTIMER_ARCH_H_ */

core/include/io.h

@@ -1,10 +1,22 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
 /**
- * @ingroup	kernel
+ * @defgroup    core_io IO Interface
+ * @brief       Interface to system io functions
+ * @ingroup     core
  * @{
+ *
  * @file        io.h
- * @brief       prototypes for system io functions
+ * @brief       Prototypes for system io functions
+ *
  * @author      INRIA
- * @author		Oliver Hahm <oliver.hahm@inria.fr>
+ * @author      Oliver Hahm <oliver.hahm@inria.fr>
  */
 
 #ifndef IO_H
@@ -12,5 +24,5 @@
 
 int fw_puts(char *data, int count);
 
-/** @} */
+/**  @} */
 #endif /* IO_H */

core/include/irq.h

@@ -1,23 +1,26 @@
-#ifndef IRQ_H_
-#define IRQ_H_
-
-/**
- * @defgroup    irq     IRQ Handling
- * @ingroup     kernel
- *
- * Provides an API to control interrupt processing.
+/*
+ * Copyright (C) 2013 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
+ * details.
  */
 
 /**
- * @file
+ * @defgroup    core_irq     IRQ Handling
+ * @ingroup     core
+ * @brief       Provides an API to control interrupt processing
+ * @{
+ *
+ * @file        irq.h
  * @brief       IRQ driver interface
  *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
- *
  */
 
+#ifndef IRQ_H_
+#define IRQ_H_
+
 #include <stdbool.h>
 
 /**
@@ -54,5 +57,5 @@ void restoreIRQ(unsigned state);
  */
 int inISR(void);
 
-/** @} */ // end of group dev_irq
+/**  @} */
 #endif /* IRQ_H_ */

core/include/kernel.h

@@ -1,27 +1,25 @@
-/**
- * Kernel compile time configuration
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup kernel
- * @{
- * @file
- * @author Freie Universität Berlin, Computer Systems & Telematics
- * @author Kaspar Schleiser <kaspar@schleiser.de>
  */
 
-#ifndef KERNEL_H_
-#define KERNEL_H_
-
 /**
- * @defgroup    kernel  Kernel
+ * @addtogroup  core_internal
  * @{
+ *
+ * @file        kernel.h
+ * @brief       Kernel compile time configuration
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
  */
 
+#ifndef KERNEL_H_
+#define KERNEL_H_
+
 #include <stdbool.h>
 #include "config.h"
 #include "tcb.h"
@@ -30,15 +28,8 @@
 #include "sched.h"
 #include "cpu-conf.h"
 
-/* ------------------------------------------------------------------------- */
-/**
- * @name Kernel Compile-Time Configuration
- * @{
- */
-
 /**
  * @def KERNEL_CONF_STACKSIZE_DEFAULT
- * @ingroup conf
  * @brief A reasonable default stack size that will suffice most smaller tasks
  */
 #ifndef KERNEL_CONF_STACKSIZE_DEFAULT
@@ -47,7 +38,6 @@
 
 /**
  * @def KERNEL_CONF_STACKSIZE_IDLE
- * @ingroup conf
  * @brief Size of the idle task's stack in bytes
  */
 #ifndef KERNEL_CONF_STACKSIZE_IDLE
@@ -65,14 +55,12 @@
 
 /**
  * @def KERNEL_CONF_STACKSIZE_MAIN
- * @ingroup conf
  * @brief Size of the main task's stack in bytes
  */
 #ifndef KERNEL_CONF_STACKSIZE_MAIN
 #define KERNEL_CONF_STACKSIZE_MAIN      (KERNEL_CONF_STACKSIZE_DEFAULT + KERNEL_CONF_STACKSIZE_PRINTF)
 #endif
 
-/** @} */
 /* ------------------------------------------------------------------------- */
 
 

core/include/kernel_internal.h

@@ -1,10 +1,20 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
 /**
- * @ingroup	kernel
+ * @addtogroup  core_internal
  * @{
+ *
  * @file        kernel_internal.h
  * @brief       prototypes for kernel internal functions
+ *
  * @author      INRIA
- * @author		Oliver Hahm <oliver.hahm@inria.fr>
+ * @author      Oliver Hahm <oliver.hahm@inria.fr>
  */
 
 #ifndef KERNEL_INTERNAL_H_
@@ -41,5 +51,14 @@ void sched_task_exit(void);
  */
 void thread_print_stack(void);
 
+/**
+ * @brief   Calculates stack usage if thread was created using CREATE_STACKTEST
+ *
+ * @param[in] stack The thread's stack
+ *
+ * @return  The current usage (overwritten addresses) of the thread's stack
+ */
+int thread_measure_stack_usage(char *stack);
+
 /** @} */
 #endif /* KERNEL_INTERNAL_H_ */

core/include/lifo.h

@@ -1,3 +1,20 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
+/**
+ * @addtogroup  core_util
+ * @{
+ *
+ * @file        lifo.h
+ * @brief       LIFO buffer API
+ *
+ */
+
 #ifndef __LIFO_H
 #define __LIFO_H
 
@@ -6,4 +23,5 @@ void lifo_init(int *array, int n);
 void lifo_insert(int *array, int i);
 int lifo_get(int *array);
 
+/** @} */
 #endif /* __LIFO_H */

core/include/lpm.h

@@ -1,24 +1,27 @@
-#ifndef LPM_H_
-#define LPM_H_
-
-/**
- * @defgroup    lpm     Power Management
- * @ingroup     kernel
- * @{
+/*
+ * Copyright (C) 2013 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
+ * details.
  */
 
 /**
- * @file
- * @brief       Power Management Interface
+ * @defgroup    core_lpm Power Management
+ * @ingroup     core
+ * @brief       The kernels power management interface
+ * @{
  *
- * @author      Freie Universität Berlin, Computer Systems & Telematics
- * @version     $Revision$
+ * @file        lpm.h
+ * @brief       Power management interface
  *
  * This interface needs to be implemented for each platform.
  *
- * @note        $Id$
+ * @author      Freie Universität Berlin, Computer Systems & Telematics
  */
 
+#ifndef LPM_H_
+#define LPM_H_
 
 /**
  * @brief   Available power modes

core/include/msg.h

@@ -1,19 +1,29 @@
-/**
- *  There are two ways to use the IPC Messaging system of RIOT. The default is synchronous
- *  messaging. In this manner, messages are either dropped when the receiver is not waiting and the
- *  message was sent non-blocking, or will be delivered immediately when the receiver calls
- *  msg_receive(msg_t* m). To use asynchronous messaging any thread can create its own queue by
- *  calling msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non full message
- *  queue are never dropped and the sending never blocks. Threads with a full message queue behaves
- *  like in synchronous mode.
- *
- * @defgroup    kernel_msg  Messaging / IPC
- * @ingroup     kernel
- * @{
+/*
+ * Copyright (C) 2013 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
+ * details.
  */
 
 /**
- * @file
+ * @defgroup    core_msg  Messaging / IPC
+ * @ingroup     core
+ * @brief       Messaging API for inter process communication
+ *
+ * There are two ways to use the IPC Messaging system of RIOT. The default is synchronous
+ * messaging. In this manner, messages are either dropped when the receiver is not waiting and the
+ * message was sent non-blocking, or will be delivered immediately when the receiver calls
+ * msg_receive(msg_t* m). To use asynchronous messaging any thread can create its own queue by
+ * calling msg_init_queue(msg_t* array, int num). Messages sent to a thread with a non full message
+ * queue are never dropped and the sending never blocks. Threads with a full message queue behaves
+ * like in synchronous mode.
+ * 
+ * @{ 
+ *
+ * @file        msg.h
+ * @brief       Messaging API for inter process communication
+ *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */

core/include/mutex.h

@@ -1,11 +1,20 @@
-/**
- * @defgroup mutex Mutexes / Synchronization
- * @ingroup kernel
- * @{
+/*
+ * Copyright (C) 2013 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
+ * details.
  */
 
 /**
- * @file
+ * @defgroup    core_sync Synchronization
+ * @brief       Mutex for thread synchronization
+ * @ingroup     core
+ * @{
+ *
+ * @file        mutex.h
+ * @brief       RIOT synchronization API
+ *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */
@@ -74,4 +83,3 @@ void mutex_wait(struct mutex_t *mutex);
 
 /** @} */
 #endif /* _MUTEX_H */
-

core/include/oneway_malloc.h

@@ -1,7 +1,18 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
 /**
- * @ingroup kernel
+ * @addtogroup  core_util
  * @{
- * @file
+ *
+ * @file        oneway_malloc.h
+ * @brief       Malloc interface
+ *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */

core/include/queue.h

@@ -1,7 +1,20 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
 /**
- * @ingroup kernel
+ * @addtogroup  core_util
  * @{
- * @file
+ *
+ * @file        queue.h
+ * @brief       A simple queue implementation
+ *
+ * TODO document functions and datastructures
+ *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */
@@ -37,4 +50,4 @@ void queue_print_node(queue_node_t *node);
 #endif
 
 /** @} */
-#endif // __QUEUE_H
+#endif /* __QUEUE_H */

core/include/sched.h

@@ -1,7 +1,20 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
 /**
- * @ingroup kernel
+ * @defgroup    core_sched Scheduler
+ * @ingroup     core
+ * @brief       The RIOT scheduler
  * @{
+ *
  * @file        sched.h
+ * @brief       Scheduler API definion
+ *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */

core/include/tcb.h

@@ -1,18 +1,23 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+ 
 /**
- * @ingroup kernel
+ * @addtogroup  core_thread
  * @{
- * @file
+ *
+ * @file        tcb.h
+ * @brief       Thread context block definition
+ *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
+ * @author      Heiko Will
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */
 
-/*
- * tcb.h
- *
- *  Created on: 19.08.2008
- *      Author: heiko, kaspar
- */
-
 #ifndef TCB_H_
 #define TCB_H_
 
@@ -23,17 +28,17 @@
 #include <msg.h>
 
 /* uneven means has to be on runqueue */
-#define STATUS_NOT_FOUND 		(0x0000)
-#define STATUS_ON_RUNQUEUE 		(0x0001)
-#define STATUS_RUNNING 			(0x0002 + STATUS_ON_RUNQUEUE)
-#define STATUS_PENDING 			(0x0004 + STATUS_ON_RUNQUEUE)
-#define STATUS_STOPPED 			(0x0008)
-#define STATUS_SLEEPING 		(0x0010)
-#define STATUS_MUTEX_BLOCKED 	(0x0020)
-#define STATUS_RECEIVE_BLOCKED 	(0x0040)
-#define STATUS_SEND_BLOCKED 	(0x0080)
-#define STATUS_REPLY_BLOCKED 	(0x0100)
-#define STATUS_TIMER_WAITING	(0x0200)
+#define STATUS_NOT_FOUND        (0x0000)
+#define STATUS_ON_RUNQUEUE      (0x0001)
+#define STATUS_RUNNING          (0x0002 + STATUS_ON_RUNQUEUE)
+#define STATUS_PENDING          (0x0004 + STATUS_ON_RUNQUEUE)
+#define STATUS_STOPPED          (0x0008)
+#define STATUS_SLEEPING         (0x0010)
+#define STATUS_MUTEX_BLOCKED    (0x0020)
+#define STATUS_RECEIVE_BLOCKED  (0x0040)
+#define STATUS_SEND_BLOCKED     (0x0080)
+#define STATUS_REPLY_BLOCKED    (0x0100)
+#define STATUS_TIMER_WAITING    (0x0200)
 
 typedef struct tcb_t {
     char *sp;

core/include/thread.h

@@ -1,24 +1,34 @@
-#ifndef __THREAD_H
-#define __THREAD_H
-
-/**
- * @defgroup    thread  Threading
- * @ingroup     kernel
- * @{
+/*
+ * Copyright (C) 2013 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
+ * details.
  */
 
 /**
- * @file
+ * @defgroup    core_thread Threading
+ * @ingroup     core
+ * @brief       Support for multi-threading
+ * @{
+ *
+ * @file        thread.h
+ * @brief       Threading API
+ *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
  */
 
+#ifndef __THREAD_H
+#define __THREAD_H
+
+
 #include <kernel.h>
 #include <tcb.h>
 
 /** Minimum stack size */
 #ifndef MINIMUM_STACK_SIZE
-#define MINIMUM_STACK_SIZE	(sizeof(tcb_t))
+#define MINIMUM_STACK_SIZE  (sizeof(tcb_t))
 #endif
 
 /**

core/kernel_init.c

@@ -1,16 +1,20 @@
-/**
- * platform-independent kernel initialization
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup kernel
+ */
+
+/**
+ * @ingroup     core_internal
  * @{
- * @file
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        kernel_init.c
+ * @brief       Platform-independent kernel initilization
+ *
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
+ *
  * @}
  */
 

core/lifo.c

@@ -1,3 +1,21 @@
+/*
+ * Copyright (C) 2013 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
+ * details.
+ */
+
+/**
+ * @ingroup     core_util
+ * @{
+ *
+ * @file        lifo.c
+ * @brief       LIFO buffer implementation
+ *
+ * @}
+ */
+
 #include <lifo.h>
 
 int lifo_empty(int *array)

core/msg.c

@@ -1,18 +1,22 @@
-/**
- * kernel messaging implementation
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup kernel_msg
+ */
+
+/**
+ * @ingroup     core_msg
  * @{
+ *
  * @file
- * @author Freie Universität Berlin, Computer Systems & Telematics, FeuerWhere project
- * @author Kaspar Schleiser <kaspar@schleiser.de>
- * @author Oliver Hahm <oliver.hahm@inria.fr>
+ * @brief       Kernel messaging implementation
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics, FeuerWhere project
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
+ * @author      Oliver Hahm <oliver.hahm@inria.fr>
+ *
  * @}
  */
 

core/mutex.c

@@ -1,16 +1,20 @@
-/**
- * kernel mutex implementation
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup kernel
+ */
+
+/**
+ * @ingroup     core_sync
  * @{
- * @file
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        mutex.c
+ * @brief       Kernel mutex implementation
+ *
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
+ *
  * @}
  */
 
@@ -113,4 +117,3 @@ void mutex_unlock(struct mutex_t *mutex)
 
     restoreIRQ(irqstate);
 }
-

core/oneway_malloc.c

@@ -1,4 +1,4 @@
-/**
+/*
  * simple malloc wrapper for sbrk
  *
  * Needed on platforms without malloc in libc, e.g. msb430
@@ -8,11 +8,18 @@
  * 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
  * details.
- *
- * @ingroup kernel
+
+/**
+ * @ingroup     core_util
  * @{
- * @file
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        oneway_malloc.c
+ * @brief       Simple malloc wrapper for SBRK
+ * 
+ * Simple malloc implementation for plattforms without malloc in libc.
+ * 
+ * @author      Kaspar Schleiser <kaspar.schleiser@fu-berlin.de>
+ *
  * @}
  */
 
@@ -63,4 +70,3 @@ void _free(void *ptr)
 
     DEBUG("_free(): block at 0x%X lost.\n", (unsigned int)ptr);
 }
-

core/queue.c

@@ -1,16 +1,20 @@
-/**
- * simple queue implementation
- *
+/*
  * Copyright (C) 2013 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
  * details.
- *
- * @ingroup kernel
+ */
+ 
+/**
+ * @ingroup     core_util
  * @{
- * @file
- * @author Kaspar Schleiser <kaspar@schleiser.de>
+ *
+ * @file        queue.c
+ * @brief       A simple queue implementation
+ *
+ * @author      Freie Universität Berlin, Computer Systems & Telematics