From c9be79def630f153b0b2d28e905939c15743f989 Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Tue, 23 Aug 2011 10:09:08 +0000
Subject: Kernel documentation fixes and improvements.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@3251 35acf78f-673a-0410-8e92-d51de3d6d3f4
---
 os/kernel/include/chbsem.h     |  5 +++++
 os/kernel/include/chdebug.h    | 11 ++++++++++-
 os/kernel/include/chevents.h   |  5 +++++
 os/kernel/include/chfiles.h    |  7 +++++++
 os/kernel/include/chioch.h     | 26 ++++++++++++++++++++++----
 os/kernel/include/chmboxes.h   |  5 +++++
 os/kernel/include/chmsg.h      |  5 +++++
 os/kernel/include/chmtx.h      |  5 +++++
 os/kernel/include/chqueues.h   | 35 +++++++++++++++++++++++++----------
 os/kernel/include/chregistry.h |  6 +++++-
 os/kernel/include/chschd.h     |  5 +++++
 os/kernel/include/chsem.h      |  5 +++++
 os/kernel/include/chstreams.h  |  5 +++++
 os/kernel/include/chsys.h      | 13 +++++++++++++
 os/kernel/include/chthreads.h  | 14 ++++++++++----
 os/kernel/include/chvt.h       | 11 ++++++++---
 os/kernel/src/chmsg.c          |  2 +-
 17 files changed, 141 insertions(+), 24 deletions(-)

diff --git a/os/kernel/include/chbsem.h b/os/kernel/include/chbsem.h
index e0e1ca865..2d8815c3c 100644
--- a/os/kernel/include/chbsem.h
+++ b/os/kernel/include/chbsem.h
@@ -84,6 +84,10 @@ typedef struct  {
 #define BSEMAPHORE_DECL(name, taken)                                        \
   BinarySemaphore name = _BSEMAPHORE_DATA(name, taken)
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Initializes a binary semaphore.
  *
@@ -238,6 +242,7 @@ typedef struct  {
  * @iclass
  */
 #define chBSemGetStateI(bsp) ((bsp)->bs_sem.s_cnt > 0 ? FALSE : TRUE)
+/** @} */
 
 #endif /* CH_USE_SEMAPHORES */
 
diff --git a/os/kernel/include/chdebug.h b/os/kernel/include/chdebug.h
index f3bf6b026..d11eb2eb2 100644
--- a/os/kernel/include/chdebug.h
+++ b/os/kernel/include/chdebug.h
@@ -132,7 +132,10 @@ extern ch_trace_buffer_t dbg_trace_buffer;
 /*===========================================================================*/
 
 #if CH_DBG_ENABLE_CHECKS || defined(__DOXYGEN__)
-
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Function parameter check.
  * @details If the condition check fails then the kernel panics and halts.
@@ -150,6 +153,7 @@ extern ch_trace_buffer_t dbg_trace_buffer;
     chDbgPanic(__QUOTE_THIS(func)"()");                                 \
 }
 #endif /* !defined(chDbgCheck) */
+/** @} */
 #else /* !CH_DBG_ENABLE_CHECKS */
 #define chDbgCheck(c, func) {                                           \
   (void)(c), (void)__QUOTE_THIS(func)"()";                              \
@@ -161,6 +165,10 @@ extern ch_trace_buffer_t dbg_trace_buffer;
 /*===========================================================================*/
 
 #if CH_DBG_ENABLE_ASSERTS || defined(__DOXYGEN__)
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Condition assertion.
  * @details If the condition check fails then the kernel panics with the
@@ -184,6 +192,7 @@ extern ch_trace_buffer_t dbg_trace_buffer;
     chDbgPanic(m);                                                      \
 }
 #endif /* !defined(chDbgAssert) */
+/** @} */
 #else /* !CH_DBG_ENABLE_ASSERTS */
 #define chDbgAssert(c, m, r) {(void)(c);}
 #endif /* !CH_DBG_ENABLE_ASSERTS */
diff --git a/os/kernel/include/chevents.h b/os/kernel/include/chevents.h
index f4314aeb2..de89118b4 100644
--- a/os/kernel/include/chevents.h
+++ b/os/kernel/include/chevents.h
@@ -88,6 +88,10 @@ typedef void (*evhandler_t)(eventid_t);
  */
 #define EVENT_MASK(eid) ((eventmask_t)(1 << (eid)))
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Registers an Event Listener on an Event Source.
  * @note    Multiple Event Listeners can use the same event identifier, the
@@ -151,6 +155,7 @@ typedef void (*evhandler_t)(eventid_t);
  * @iclass
  */
 #define chEvtBroadcastI(esp) chEvtBroadcastFlagsI(esp, 0)
+/** @} */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/os/kernel/include/chfiles.h b/os/kernel/include/chfiles.h
index ff3f8274e..69a63965e 100644
--- a/os/kernel/include/chfiles.h
+++ b/os/kernel/include/chfiles.h
@@ -74,6 +74,8 @@ typedef uint32_t fileoffset_t;
   _base_sequential_stream_data
 
 /**
+ * @extends BaseSequentialStreamVMT
+ *
  * @brief   @p BaseFileStream virtual methods table.
  */
 struct BaseFilelStreamVMT {
@@ -92,6 +94,10 @@ typedef struct {
   _base_file_stream_data
 } BaseFileStream;
 
+/**
+ * @name    Macro Functions (BaseFileStream)
+ * @{
+ */
 /**
  * @brief   Base file Stream close.
  * @details The function closes a file stream.
@@ -138,6 +144,7 @@ typedef struct {
  * @api
  */
 #define chFileStreamSeek ((ip)->vmt->lseek(ip, offset))
+/** @} */
 
 #endif /* _CHFILES_H_ */
 
diff --git a/os/kernel/include/chioch.h b/os/kernel/include/chioch.h
index 02757c7e9..3361926e3 100644
--- a/os/kernel/include/chioch.h
+++ b/os/kernel/include/chioch.h
@@ -67,6 +67,8 @@
   _base_sequential_stream_data
 
 /**
+ * @extends BaseSequentialStreamVMT
+ *
  * @brief   @p BaseChannel virtual methods table.
  */
 struct BaseChannelVMT {                                                     \
@@ -86,6 +88,10 @@ typedef struct {
   _base_channel_data
 } BaseChannel;
 
+/**
+ * @name    Macro Functions (BaseChannel)
+ * @{
+ */
 /**
  * @brief   Channel output check.
  * @details This function verifies if a subsequent put/write operation would
@@ -227,9 +233,13 @@ typedef struct {
  */
 #define chIOReadTimeout(ip, bp, n, time)                                    \
   ((ip)->vmt->readt(ip, bp, n, time))
+/** @} */
 
-#if CH_USE_EVENTS
-
+#if CH_USE_EVENTS || defined(__DOXYGEN__)
+/**
+ * @name    I/O status flags
+ * @{
+ */
 /** @brief No pending conditions.*/
 #define IO_NO_ERROR             0
 /** @brief Connection happened.*/
@@ -242,6 +252,7 @@ typedef struct {
 #define IO_OUTPUT_EMPTY         8
 /** @brief Transmission end.*/
 #define IO_TRANSMISSION_END     16
+/** @} */
 
 /**
  * @brief   Type of an I/O condition flags mask.
@@ -267,6 +278,8 @@ typedef uint_fast16_t ioflags_t;
   ioflags_t             flags;
 
 /**
+ * @extends BaseChannelVMT
+ *
  * @brief   @p BaseAsynchronousChannel virtual methods table.
  */
 struct BaseAsynchronousChannelVMT {
@@ -286,6 +299,10 @@ typedef struct {
   _base_asynchronous_channel_data
 } BaseAsynchronousChannel;
 
+/**
+ * @name    Macro Functions (BaseAsynchronousChannel)
+ * @{
+ */
 /**
  * @brief   Returns the I/O condition event source.
  * @details The event source is broadcasted when an I/O condition happens.
@@ -299,7 +316,7 @@ typedef struct {
 #define chIOGetEventSource(ip) (&((ip)->event))
 
 /**
- * @brief   Adds condition flags to the channel's mask.
+ * @brief   Adds status flags to the channel's mask.
  * @details This function is usually called from the I/O ISTs in order to
  *          notify I/O conditions such as data events, errors, signal
  *          changes etc.
@@ -316,7 +333,7 @@ typedef struct {
 }
 
 /**
- * @brief   Returns and clears the errors mask associated to the channel.
+ * @brief   Returns and clears the status flags associated to the channel.
  *
  * @param[in] ip        pointer to a @p BaseAsynchronousChannel or derived
  *                      class
@@ -326,6 +343,7 @@ typedef struct {
  * @api
  */
 #define chIOGetAndClearFlags(ip) ((ip)->vmt->getflags(ip))
+/** @} */
 
 /**
  * @brief   Default implementation of the @p getflags virtual method.
diff --git a/os/kernel/include/chmboxes.h b/os/kernel/include/chmboxes.h
index 4a1706302..60cb7a5c1 100644
--- a/os/kernel/include/chmboxes.h
+++ b/os/kernel/include/chmboxes.h
@@ -72,6 +72,10 @@ extern "C" {
 }
 #endif
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Returns the mailbox buffer size.
  *
@@ -120,6 +124,7 @@ extern "C" {
  * @iclass
  */
 #define chMBPeekI(mbp) (*(mbp)->mb_rdptr)
+/** @} */
 
 /**
  * @brief   Data part of a static mailbox initializer.
diff --git a/os/kernel/include/chmsg.h b/os/kernel/include/chmsg.h
index 1803c719d..2bae02dea 100644
--- a/os/kernel/include/chmsg.h
+++ b/os/kernel/include/chmsg.h
@@ -31,6 +31,10 @@
 
 #if CH_USE_MESSAGES || defined(__DOXYGEN__)
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Evaluates to TRUE if the thread has pending messages.
  *
@@ -74,6 +78,7 @@
  * @sclass
  */
 #define chMsgReleaseS(tp, msg) chSchWakeupS(tp, msg)
+/** @} */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/os/kernel/include/chmtx.h b/os/kernel/include/chmtx.h
index 9f2d5a0d3..831d48a89 100644
--- a/os/kernel/include/chmtx.h
+++ b/os/kernel/include/chmtx.h
@@ -76,6 +76,10 @@ extern "C" {
  */
 #define MUTEX_DECL(name) Mutex name = _MUTEX_DATA(name)
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Returns @p TRUE if the mutex queue contains at least a waiting
  *          thread.
@@ -83,6 +87,7 @@ extern "C" {
  * @sclass
  */
 #define chMtxQueueNotEmptyS(mp) notempty(&(mp)->m_queue)
+/** @} */
 
 #endif /* CH_USE_MUTEXES */
 
diff --git a/os/kernel/include/chqueues.h b/os/kernel/include/chqueues.h
index fa217710b..4917ac837 100644
--- a/os/kernel/include/chqueues.h
+++ b/os/kernel/include/chqueues.h
@@ -70,6 +70,10 @@ struct GenericQueue {
   qnotify_t             q_notify;   /**< @brief Data notification callback. */
 };
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Returns the queue's buffer size.
  *
@@ -90,7 +94,8 @@ struct GenericQueue {
  *
  * @iclass
  */
-#define chQSpaceI(qp) ((size_t)((qp)->q_counter))
+#define chQSpaceI(qp) ((qp)->q_counter)
+/** @} */
 
 /**
  * @extends GenericQueue
@@ -105,6 +110,10 @@ struct GenericQueue {
  */
 typedef GenericQueue InputQueue;
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Returns the filled space into an input queue.
  *
@@ -165,6 +174,7 @@ typedef GenericQueue InputQueue;
  * @api
  */
 #define chIQGet(iqp) chIQGetTimeout(iqp, TIME_INFINITE)
+/** @} */
 
 /**
  * @brief   Data part of a static input queue initializer.
@@ -212,15 +222,19 @@ typedef GenericQueue InputQueue;
  */
 typedef GenericQueue OutputQueue;
 
- /**
-  * @brief   Returns the filled space into an output queue.
-  *
-  * @param[in] oqp       pointer to an @p OutputQueue structure
-  * @return              The number of full bytes in the queue.
-  * @retval 0            if the queue is empty.
-  *
-  * @iclass
-  */
+/**
+ * @name    Macro Functions
+ * @{
+ */
+/**
+ * @brief   Returns the filled space into an output queue.
+ *
+ * @param[in] oqp       pointer to an @p OutputQueue structure
+ * @return              The number of full bytes in the queue.
+ * @retval 0            if the queue is empty.
+ *
+ * @iclass
+ */
 #define chOQGetFullI(oqp) (chQSizeI(oqp) - chQSpaceI(oqp))
 
 /**
@@ -274,6 +288,7 @@ typedef GenericQueue OutputQueue;
  * @api
  */
 #define chOQPut(oqp, b) chOQPutTimeout(oqp, b, TIME_INFINITE)
+ /** @} */
 
 /**
  * @brief   Data part of a static output queue initializer.
diff --git a/os/kernel/include/chregistry.h b/os/kernel/include/chregistry.h
index 0967f699e..8f7ebd4b9 100644
--- a/os/kernel/include/chregistry.h
+++ b/os/kernel/include/chregistry.h
@@ -30,6 +30,10 @@
 #define _CHREGISTRY_H_
 
 #if CH_USE_REGISTRY || defined(__DOXYGEN__)
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Sets the current thread name.
  * @pre     This function only stores the pointer to the name if the option
@@ -52,13 +56,13 @@
  * @retval NULL         if the thread name has not been set.
  */
 #define chRegGetThreadName(tp) ((tp)->p_name)
+/** @} */
 #else /* !CH_USE_REGISTRY */
 #define chRegSetThreadName(p)
 #define chRegGetThreadName(tp) NULL
 #endif /* !CH_USE_REGISTRY */
 
 #if CH_USE_REGISTRY || defined(__DOXYGEN__)
-
 /**
  * @brief   Removes a thread from the registry list.
  * @note    This macro is not meant for use in application code.
diff --git a/os/kernel/include/chschd.h b/os/kernel/include/chschd.h
index 27f6b9222..0e490c26a 100644
--- a/os/kernel/include/chschd.h
+++ b/os/kernel/include/chschd.h
@@ -161,6 +161,10 @@ extern "C" {
 }
 #endif
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Determines if the current thread must reschedule.
  * @details This function returns @p TRUE if there is a ready thread with
@@ -223,6 +227,7 @@ extern "C" {
     chSchDoReschedule();                                                    \
 }
 #endif /* CH_TIME_QUANTUM == 0 */
+/** @} */
 
 #endif /* _CHSCHD_H_ */
 
diff --git a/os/kernel/include/chsem.h b/os/kernel/include/chsem.h
index 04e079466..5f1c37a0a 100644
--- a/os/kernel/include/chsem.h
+++ b/os/kernel/include/chsem.h
@@ -82,6 +82,10 @@ extern "C" {
  */
 #define SEMAPHORE_DECL(name, n) Semaphore name = _SEMAPHORE_DATA(name, n)
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Decreases the semaphore counter.
  * @details This macro can be used when the counter is known to be positive.
@@ -105,6 +109,7 @@ extern "C" {
  * @iclass
  */
 #define chSemGetCounterI(sp)    ((sp)->s_cnt)
+/** @} */
 
 #endif /* CH_USE_SEMAPHORES */
 
diff --git a/os/kernel/include/chstreams.h b/os/kernel/include/chstreams.h
index 0bd763366..57883601d 100644
--- a/os/kernel/include/chstreams.h
+++ b/os/kernel/include/chstreams.h
@@ -73,6 +73,10 @@ typedef struct {
   _base_sequential_stream_data
 } BaseSequentialStream;
 
+/**
+ * @name    Macro Functions (BaseSequentialStream)
+ * @{
+ */
 /**
  * @brief   Sequential Stream write.
  * @details The function writes data from a buffer to a stream.
@@ -103,6 +107,7 @@ typedef struct {
  * @api
  */
 #define chSequentialStreamRead(ip, bp, n) ((ip)->vmt->read(ip, bp, n))
+/** @} */
 
 #endif /* _CHSTREAMS_H_ */
 
diff --git a/os/kernel/include/chsys.h b/os/kernel/include/chsys.h
index f807182ac..b69736a1d 100644
--- a/os/kernel/include/chsys.h
+++ b/os/kernel/include/chsys.h
@@ -29,6 +29,10 @@
 #ifndef _CHSYS_H_
 #define _CHSYS_H_
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 #if !CH_NO_IDLE_THREAD || defined(__DOXYGEN__)
 /**
  * @brief   Returns a pointer to the idle thread.
@@ -177,7 +181,11 @@
   dbg_check_unlock_from_isr();                                              \
   port_unlock_from_isr();                                                   \
 }
+/** @} */
 
+/**
+ * @name    ISRs abstraction macros
+ */
 /**
  * @brief   IRQ handler enter code.
  * @note    Usually IRQ handlers functions are also declared naked.
@@ -211,7 +219,11 @@
  * @special
  */
 #define CH_IRQ_HANDLER(id) PORT_IRQ_HANDLER(id)
+/** @} */
 
+/**
+ * @name    Fast ISRs abstraction macros
+ */
 /**
  * @brief   Standard fast IRQ handler declaration.
  * @note    @p id can be a function name or a vector number depending on the
@@ -221,6 +233,7 @@
  * @special
  */
 #define CH_FAST_IRQ_HANDLER(id) PORT_FAST_IRQ_HANDLER(id)
+/** @} */
 
 #ifdef __cplusplus
 extern "C" {
diff --git a/os/kernel/include/chthreads.h b/os/kernel/include/chthreads.h
index eb3d8bb14..bd3f21296 100644
--- a/os/kernel/include/chthreads.h
+++ b/os/kernel/include/chthreads.h
@@ -59,9 +59,10 @@
  */
 #define THD_MEM_MODE_MASK       3   /**< @brief Thread memory mode mask.    */
 #define THD_MEM_MODE_STATIC     0   /**< @brief Static thread.              */
-#define THD_MEM_MODE_HEAP       1   /**< @brief Thread allocated from Heap. */
-#define THD_MEM_MODE_MEMPOOL    2   /**< @brief Thread allocated from Memory
-                                         Pool.                              */
+#define THD_MEM_MODE_HEAP       1   /**< @brief Thread allocated from a
+                                         Memory Heap.                       */
+#define THD_MEM_MODE_MEMPOOL    2   /**< @brief Thread allocated from a
+                                         Memory Pool.                       */
 #define THD_TERMINATE           4   /**< @brief Termination requested flag. */
 /** @} */
 
@@ -204,6 +205,10 @@ struct Thread {
  */
 typedef msg_t (*tfunc_t)(void *);
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Returns a pointer to the current @p Thread.
  *
@@ -258,7 +263,7 @@ typedef msg_t (*tfunc_t)(void *);
 #define chThdShouldTerminate() (currp->p_flags & THD_TERMINATE)
 
 /**
- * @brief   Resumes a thread created with @p chThdInit().
+ * @brief   Resumes a thread created with @p chThdCreateI().
  *
  * @param[in] tp        pointer to the thread
  *
@@ -317,6 +322,7 @@ typedef msg_t (*tfunc_t)(void *);
  * @api
  */
 #define chThdSleepMicroseconds(usec) chThdSleep(US2ST(usec))
+/** @} */
 
 /*
  * Threads APIs.
diff --git a/os/kernel/include/chvt.h b/os/kernel/include/chvt.h
index fe4ba11df..0038e3d0a 100644
--- a/os/kernel/include/chvt.h
+++ b/os/kernel/include/chvt.h
@@ -34,21 +34,21 @@
  * @{
  */
 /**
- * @brief   Time conversion utility.
+ * @brief   Seconds to system ticks.
  * @details Converts from seconds to system ticks number.
  * @note    The result is rounded upward to the next tick boundary.
  */
 #define S2ST(sec)   ((systime_t)((sec) * CH_FREQUENCY))
 
 /**
- * @brief   Time conversion utility.
+ * @brief   Milliseconds t0 system ticks.
  * @details Converts from milliseconds to system ticks number.
  * @note    The result is rounded upward to the next tick boundary.
  */
 #define MS2ST(msec) ((systime_t)(((((msec) - 1L) * CH_FREQUENCY) / 1000L) + 1L))
 
 /**
- * @brief   Time conversion utility.
+ * @brief   Microseconds to system ticks.
  * @details Converts from microseconds to system ticks number.
  * @note    The result is rounded upward to the next tick boundary.
  */
@@ -99,6 +99,10 @@ typedef struct {
 
 extern VTList vtlist;
 
+/**
+ * @name    Macro Functions
+ * @{
+ */
 /**
  * @brief   Virtual timers ticker.
  *
@@ -139,6 +143,7 @@ extern VTList vtlist;
  * @api
  */
 #define chTimeNow() (vtlist.vt_systime)
+/** @} */
 
 /*
  * Virtual Timers APIs.
diff --git a/os/kernel/src/chmsg.c b/os/kernel/src/chmsg.c
index 5002a892a..403df1580 100644
--- a/os/kernel/src/chmsg.c
+++ b/os/kernel/src/chmsg.c
@@ -109,7 +109,7 @@ Thread *chMsgWait(void) {
 }
 
 /**
- * @brief   Releases the thread waiting on top of the messages queue.
+ * @brief   Releases a sender thread specifying a response message.
  * @pre     Invoke this function only after a message has been received
  *          using @p chMsgWait().
  *
-- 
cgit v1.2.3