[kernel] add some documentation

include/kernel/event.h

@@ -58,6 +58,7 @@ status_t event_wait(event_t *);
 status_t event_wait_timeout(event_t *, time_t); /* wait on the event with a timeout */
 status_t event_signal(event_t *, bool reschedule);
 status_t event_unsignal(event_t *);
+#define event_initialized(e)	((e)->magic == EVENT_MAGIC)
 
 #endif
 

kernel/debug.c

@@ -21,6 +21,16 @@
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
 
+/**
+ * @defgroup debug  Debug
+ * @{
+ */
+
+/**
+ * @file
+ * @brief  Debug console functions.
+ */
+
 #include <debug.h>
 #include <kernel/thread.h>
 #include <kernel/timer.h>

kernel/event.c

@@ -20,6 +20,26 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
+
+/**
+ * @file
+ * @brief  Event wait and signal functions for threads.
+ * @defgroup event Events
+ *
+ * An event is a subclass of a wait queue.
+ *
+ * Threads wait for events, with optional timeouts.
+ *
+ * Events are "signaled", releasing waiting threads to continue.
+ * Signals may be one-shot signals (EVENT_FLAG_AUTOUNSIGNAL), in which
+ * case one signal releases only one thread, at which point it is
+ * automatically cleared. Otherwise, signals release all waiting threads
+ * to continue immediately until the signal is manually cleared with
+ * event_unsignal().
+ *
+ * @{
+ */
+
 #include <debug.h>
 #include <err.h>
 #include <kernel/event.h>
@@ -28,6 +48,13 @@
 #define EVENT_CHECK 1
 #endif
 
+/**
+ * @brief  Initialize an event object
+ *
+ * @param e        Event object to initialize
+ * @param initial  Initial value for "signaled" state
+ * @param flags    0 or EVENT_FLAG_AUTOUNSIGNAL
+ */
 void event_init(event_t *e, bool initial, uint flags)
 {
 #if EVENT_CHECK
@@ -40,6 +67,15 @@ void event_init(event_t *e, bool initial, uint flags)
 	wait_queue_init(&e->wait);
 }
 
+/**
+ * @brief  Destroy an event object.
+ *
+ * Event's resources are freed and it may no longer be
+ * used until event_init() is called again.  Any threads
+ * still waiting on the event will be resumed.
+ *
+ * @param e        Event object to initialize
+ */
 void event_destroy(event_t *e)
 {
 	enter_critical_section();
@@ -56,6 +92,21 @@ void event_destroy(event_t *e)
 	exit_critical_section();
 }
 
+/**
+ * @brief  Wait for event to be signaled
+ *
+ * If the event has already been signaled, this function
+ * returns immediately.  Otherwise, the current thread
+ * goes to sleep until the event object is signaled,
+ * the timeout is reached, or the event object is destroyed
+ * by another thread.
+ *
+ * @param e        Event object
+ * @param timeout  Timeout value, in ms
+ *
+ * @return  0 on success, ERR_TIMED_OUT on timeout,
+ *         other values on other errors.
+ */
 status_t event_wait_timeout(event_t *e, time_t timeout)
 {
 	status_t ret = NO_ERROR;
@@ -85,11 +136,31 @@ status_t event_wait_timeout(event_t *e, time_t timeout)
 	return ret;
 }
 
+/**
+ * @brief  Same as event_wait_timeout(), but without a timeout.
+ */
 status_t event_wait(event_t *e)
 {
 	return event_wait_timeout(e, INFINITE_TIME);
 }
 
+/**
+ * @brief  Signal an event
+ *
+ * Signals an event.  If EVENT_FLAG_AUTOUNSIGNAL is set in the event
+ * object's flags, only one waiting thread is allowed to proceed.  Otherwise,
+ * all waiting threads are allowed to proceed until such time as
+ * event_unsignal() is called.
+ *
+ * @param e	          Event object
+ * @param reschedule  If true, waiting thread(s) are executed immediately,
+ *                    and the current thread resumes only after the
+ *                    waiting threads have been satisfied. If false,
+ *                    waiting threads are placed at the end of the run
+ *                    queue.
+ *
+ * @return  Returns NO_ERROR on success.
+ */
 status_t event_signal(event_t *e, bool reschedule)
 {
 	enter_critical_section();
@@ -121,6 +192,18 @@ status_t event_signal(event_t *e, bool reschedule)
 	return NO_ERROR;
 }
 
+/**
+ * @brief  Clear the "signaled" property of an event
+ *
+ * Used mainly for event objects without the EVENT_FLAG_AUTOUNSIGNAL
+ * flag.  Once this function is called, threads that call event_wait()
+ * functions will once again need to wait until the event object
+ * is signaled.
+ *
+ * @param e  Event object
+ *
+ * @return  Returns NO_ERROR on success.
+ */
 status_t event_unsignal(event_t *e)
 {
 	enter_critical_section();

kernel/mutex.c

@@ -20,6 +20,15 @@
  * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  */
+
+/**
+ * @file
+ * @brief  Mutex functions
+ *
+ * @defgroup mutex Mutex
+ * @{
+ */
+
 #include <debug.h>
 #include <err.h>
 #include <kernel/mutex.h>
@@ -29,6 +38,9 @@
 #define MUTEX_CHECK 1
 #endif
 
+/**
+ * @brief  Initialize a mutex_t
+ */
 void mutex_init(mutex_t *m)
 {
 #if MUTEX_CHECK
@@ -41,6 +53,12 @@ void mutex_init(mutex_t *m)
 	wait_queue_init(&m->wait);
 }
 
+/**
+ * @brief  Destroy a mutex_t
+ *
+ * This function frees any resources that were allocated
+ * in mutex_init().  The mutex_t object itself is not freed.
+ */
 void mutex_destroy(mutex_t *m)
 {
 	enter_critical_section();
@@ -59,6 +77,14 @@ void mutex_destroy(mutex_t *m)
 	exit_critical_section();
 }
 
+/**
+ * @brief  Acquire a mutex; wait if needed.
+ *
+ * This function waits for a mutex to become available.  It
+ * may wait forever if the mutex never becomes free.
+ *
+ * @return  NO_ERROR on success, other values on error
+ */
 status_t mutex_acquire(mutex_t *m)
 {
 	status_t ret = NO_ERROR;
@@ -94,6 +120,16 @@ status_t mutex_acquire(mutex_t *m)
 	return ret;
 }
 
+/**
+ * @brief  Mutex wait with timeout
+ *
+ * This function waits up to \a timeout ms for the mutex to become available.
+ * Timeout may be zero, in which case this function returns immediately if
+ * the mutex is not free.
+ *
+ * @return  NO_ERROR on success, ERR_TIMED_OUT on timeout,
+ * other values on error
+ */
 status_t mutex_acquire_timeout(mutex_t *m, time_t timeout)
 {
 	status_t ret = NO_ERROR;
@@ -140,6 +176,9 @@ status_t mutex_acquire_timeout(mutex_t *m, time_t timeout)
 	return ret;
 }
 
+/**
+ * @brief  Release mutex
+ */
 status_t mutex_release(mutex_t *m)
 {
 	if (current_thread != m->holder)