Merge pull request #977 from mehlis/doxygen-irq

core: kernel: improved doxygen documentation

core/include/irq.h

@@ -29,13 +29,22 @@
  *
  * @note    This function should be used in favour of dINT().
  *
- * @return  previous value of status register
+ * @return  Previous value of status register. The return value should not
+ *          interpreted as a boolean value. The actual value is only
+ *          significant for restoreIRQ().
+ *
+ * @see     restoreIRQ
  */
 unsigned disableIRQ(void);
 
 /**
  * @brief   This function clears the IRQ disable bit in the status register
- * @return  previous value of status register
+ *
+ * @note    This function should be used in favour of eINT().
+ *
+ * @return  Previous value of status register. The return value should not
+ *          interpreted as a boolean value. The actual value is only
+ *          significant for restoreIRQ().
  *
  * @see     restoreIRQ
  */
@@ -44,10 +53,12 @@ unsigned enableIRQ(void);
 /**
  * @brief   This function restores the IRQ disable bit in the status register
  *          to the value contained within passed state
- * @param   state   state to restore
+ *
+ * @param[in] state   state to restore
  *
  * @note    This function should be used in favour of eINT().
  *
+ * @see     enableIRQ
  * @see     disableIRQ
  */
 void restoreIRQ(unsigned state);
@@ -58,5 +69,5 @@ void restoreIRQ(unsigned state);
  */
 int inISR(void);
 
-/** @} */
 #endif /* IRQ_H_ */
+/** @} */

core/include/kernel.h

@@ -13,7 +13,8 @@
  * @file        kernel.h
  * @brief       Kernel compile time configuration
  *
- * A int reboot(int mode) function is also provided (and used by core_panic() when needed).
+ *              A reboot() function is also provided
+ *              (and used by core_panic() when needed).
  *
  * @author      Freie Universität Berlin, Computer Systems & Telematics
  * @author      Kaspar Schleiser <kaspar@schleiser.de>
@@ -67,19 +68,60 @@
 
 /* ------------------------------------------------------------------------- */
 
-
+/**
+ * @def PID_NULL
+ * @brief Identifier to detect an invalid PID
+ */
 #define PID_NULL -1
 
-#define PRIORITY_MIN            SCHED_PRIO_LEVELS-1
+/**
+ * @def PRIORITY_MIN
+ * @brief Least priority a thread can have
+ */
+#define PRIORITY_MIN            (SCHED_PRIO_LEVELS-1)
 
+/**
+ * @def PRIORITY_IDLE
+ * @brief Priority of the idle thread
+ */
 #define PRIORITY_IDLE           PRIORITY_MIN
+
+/**
+ * @def PRIORITY_MAIN
+ * @brief Priority of the main thread
+ */
 #define PRIORITY_MAIN           (PRIORITY_MIN - (SCHED_PRIO_LEVELS/2))
 
+/**
+ * @def LPM_PREVENT_SLEEP_UART
+ * @brief This flag tells the kernel that the deepest power saving
+ *        mode that currently can be used must still allow UART
+ *        communication. Bitmask to use with `lpm_prevent_sleep`
+ *        in power management.
+ */
 #define LPM_PREVENT_SLEEP_UART    BIT2
+
+/**
+ * @def LPM_PREVENT_SLEEP_HWTIMER
+ * @brief This flag tells the kernel that the deepest power saving
+ *        mode that currently can be used must still allow the hwtimer
+ *        to run. Bitmask to use with `lpm_prevent_sleep` in power management.
+ */
 #define LPM_PREVENT_SLEEP_HWTIMER    BIT1
 
+/**
+ * @brief This bitfield is used to configure which modules are
+ *        currently active and prevent the kernel to go to the
+ *        deepest power modes. It is used with `LPM_PREVENT_SLEEP_HWTIMER`
+ *        and/or `LPM_PREVENT_SLEEP_UART`.
+ */
 extern volatile int lpm_prevent_sleep;
 
+/**
+ * @brief Variable used to store system configurationi
+ *
+ * @detail This contains e.g. the node ID, name, default channel and so on
+ */
 extern config_t sysconfig;
 
 /* ------------------------------------------------------------------------- */
@@ -95,7 +137,11 @@ extern config_t sysconfig;
  */
 int reboot(int mode);
 
-#define RB_AUTOBOOT 0   /* << Reboot the system in the usual fashion */
+/**
+ * @def RB_AUTOBOOT
+ * @brief Reboot the system in the usual fashion
+ */
+#define RB_AUTOBOOT 0
 
-/** @} */
 #endif /* KERNEL_H_ */
+/** @} */

core/include/kernel_internal.h

@@ -53,5 +53,5 @@ NORETURN void sched_task_exit(void);
  */
 void thread_print_stack(void);
 
-/** @} */
 #endif /* KERNEL_INTERNAL_H_ */
+/** @} */