Documentation improvements, renamed some event APIs.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2179 35acf78f-673a-0410-8e92-d51de3d6d3f4

13 files changed, 31 insertions, 26 deletions

diff --git a/os/kernel/include/chbsem.h b/os/kernel/include/chbsem.h
index adbf1605f..04d4579da 100644
--- a/os/kernel/include/chbsem.h
+++ b/os/kernel/include/chbsem.h
@@ -50,7 +50,7 @@
 #ifndef _CHBSEM_H_

 #define _CHBSEM_H_

 

-#if CH_USE_SEMAPHORES

+#if CH_USE_SEMAPHORES || defined(__DOXYGEN__)

 

 /**

  * @extends Semaphore

diff --git a/os/kernel/include/chcond.h b/os/kernel/include/chcond.h
index 8c2fc863d..5a03ddd7f 100644
--- a/os/kernel/include/chcond.h
+++ b/os/kernel/include/chcond.h
@@ -32,7 +32,7 @@
 #ifndef _CHCOND_H_

 #define _CHCOND_H_

 

-#if CH_USE_CONDVARS

+#if CH_USE_CONDVARS || defined(__DOXYGEN__)

 

 /*

  * Module dependencies check.

diff --git a/os/kernel/include/chdebug.h b/os/kernel/include/chdebug.h
index b9da339b7..e6d6f231c 100644
--- a/os/kernel/include/chdebug.h
+++ b/os/kernel/include/chdebug.h
@@ -82,7 +82,7 @@ typedef struct {
 

 #define __QUOTE_THIS(p) #p

 

-#if CH_DBG_ENABLE_CHECKS

+#if CH_DBG_ENABLE_CHECKS || defined(__DOXYGEN__)

 /**

  * @brief   Function parameter check.

  * @details If the condition check fails then the kernel panics and halts.

@@ -102,7 +102,7 @@ typedef struct {
 }

 #endif /* !CH_DBG_ENABLE_CHECKS */

 

-#if CH_DBG_ENABLE_ASSERTS

+#if CH_DBG_ENABLE_ASSERTS || defined(__DOXYGEN__)

 /**

  * @brief   Condition assertion.

  * @details If the condition check fails then the kernel panics with the

@@ -144,7 +144,7 @@ typedef struct {
 #ifdef __cplusplus

 extern "C" {

 #endif

-#if CH_DBG_ENABLE_TRACE

+#if CH_DBG_ENABLE_TRACE || defined(__DOXYGEN__)

   extern TraceBuffer trace_buffer;

   void trace_init(void);

   void chDbgTrace(Thread *otp);

diff --git a/os/kernel/include/chevents.h b/os/kernel/include/chevents.h
index ac46ae826..cf7939d57 100644
--- a/os/kernel/include/chevents.h
+++ b/os/kernel/include/chevents.h
@@ -28,7 +28,7 @@
 #ifndef _CHEVENTS_H_

 #define _CHEVENTS_H_

 

-#if CH_USE_EVENTS

+#if CH_USE_EVENTS || defined(__DOXYGEN__)

 

 typedef struct EventListener EventListener;

 

@@ -91,16 +91,18 @@ typedef struct EventSource {
  *                      The value must range between zero and the size, in bit,

  *                      of the @p eventid_t type minus one.

  */

-#define chEvtRegister(esp, elp, eid) chEvtRegisterMask(esp, elp, EVENT_MASK(eid))

+#define chEvtRegister(esp, elp, eid) \

+  chEvtRegisterMask(esp, elp, EVENT_MASK(eid))

 

 /**

  * @brief   Initializes an Event Source.

- * @note    Can be used with interrupts disabled or enabled.

+ * @note    This function can be invoked before the kernel is initialized

+ *          because it just prepares a @p EventSource structure.

  *

  * @param[in] esp       pointer to the @p EventSource structure

  */

 #define chEvtInit(esp) \

-        ((esp)->es_next = (EventListener *)(void *)(esp))

+  ((esp)->es_next = (EventListener *)(void *)(esp))

 

 /**

  * @brief   Verifies if there is at least one @p EventListener registered.

@@ -109,7 +111,7 @@ typedef struct EventSource {
  * @param[in] esp       pointer to the @p EventSource structure

  */

 #define chEvtIsListening(esp) \

-                ((void *)(esp) != (void *)(esp)->es_next)

+  ((void *)(esp) != (void *)(esp)->es_next)

 

 /**

  * @brief   Event Handler callback function.

@@ -123,8 +125,8 @@ extern "C" {
                          EventListener *elp,

                          eventmask_t mask);

   void chEvtUnregister(EventSource *esp, EventListener *elp);

-  eventmask_t chEvtClear(eventmask_t mask);

-  eventmask_t chEvtPend(eventmask_t mask);

+  eventmask_t chEvtClearFlags(eventmask_t mask);

+  eventmask_t chEvtAddFlags(eventmask_t mask);

   void chEvtSignal(Thread *tp, eventmask_t mask);

   void chEvtSignalI(Thread *tp, eventmask_t mask);

   void chEvtBroadcast(EventSource *esp);

diff --git a/os/kernel/include/chheap.h b/os/kernel/include/chheap.h
index 1cfaf2c5f..1c5ec5419 100644
--- a/os/kernel/include/chheap.h
+++ b/os/kernel/include/chheap.h
@@ -28,7 +28,7 @@
 #ifndef _CHHEAP_H_

 #define _CHHEAP_H_

 

-#if CH_USE_HEAP

+#if CH_USE_HEAP || defined(__DOXYGEN__)

 

 /*

  * Module dependencies check.

diff --git a/os/kernel/include/chmboxes.h b/os/kernel/include/chmboxes.h
index a5088b2c5..4447b02d1 100644
--- a/os/kernel/include/chmboxes.h
+++ b/os/kernel/include/chmboxes.h
@@ -28,7 +28,7 @@
 #ifndef _CHMBOXES_H_

 #define _CHMBOXES_H_

 

-#if CH_USE_MAILBOXES

+#if CH_USE_MAILBOXES || defined(__DOXYGEN__)

 

 /*

  * Module dependencies check.

@@ -37,6 +37,9 @@
 #error "CH_USE_MAILBOXES requires CH_USE_SEMAPHORES"

 #endif

 

+/**

+ * @brief   Structure representing a mailbox object.
+ */

 typedef struct {

   msg_t                 *mb_buffer;     /**< @brief Pointer to the mailbox

                                                     buffer.                 */

@@ -99,10 +102,10 @@ extern "C" {
 

 /**

  * @brief   Returns the next message in the queue without removing it.

- * @note    A message must be waiting in the queue for this function to work or

- *          it would return garbage. The correct way to use this macro is to

- *          use @p chMBGetFull() and then use this macro, all within a lock

- *          state.

+ * @pre     A message must be waiting in the queue for this function to work

+ *          or it would return garbage. The correct way to use this macro is

+ *          to use @p chMBGetFull() and then use this macro, all within a

+ *          lock state.

  */

 #define chMBPeek(mbp) (*(mbp)->mb_rdptr)

 

diff --git a/os/kernel/include/chmemcore.h b/os/kernel/include/chmemcore.h
index 4870c79f1..f42478125 100644
--- a/os/kernel/include/chmemcore.h
+++ b/os/kernel/include/chmemcore.h
@@ -51,7 +51,7 @@ typedef void *(*memgetfunc_t)(size_t size);
  */

 #define MEM_IS_ALIGNED(p)   (((size_t)(p) & MEM_ALIGN_MASK) == 0)

 

-#if CH_USE_MEMCORE

+#if CH_USE_MEMCORE || defined(__DOXYGEN__)

 

 #ifdef __cplusplus

 extern "C" {

diff --git a/os/kernel/include/chmempools.h b/os/kernel/include/chmempools.h
index 2408d1c7f..1c2e2aa70 100644
--- a/os/kernel/include/chmempools.h
+++ b/os/kernel/include/chmempools.h
@@ -28,7 +28,7 @@
 #ifndef _CHMEMPOOLS_H_

 #define _CHMEMPOOLS_H_

 

-#if CH_USE_MEMPOOLS

+#if CH_USE_MEMPOOLS || defined(__DOXYGEN__)

 

 /**

  * @brief   Memory pool free object header.

diff --git a/os/kernel/include/chmsg.h b/os/kernel/include/chmsg.h
index 1947c02f7..16f6d1ef4 100644
--- a/os/kernel/include/chmsg.h
+++ b/os/kernel/include/chmsg.h
@@ -28,7 +28,7 @@
 #ifndef _CHMSG_H_

 #define _CHMSG_H_

 

-#if CH_USE_MESSAGES

+#if CH_USE_MESSAGES || defined(__DOXYGEN__)

 

 /**

  * @brief   Evaluates to TRUE if the thread has pending messages.

diff --git a/os/kernel/include/chmtx.h b/os/kernel/include/chmtx.h
index 73a507079..c551f47bf 100644
--- a/os/kernel/include/chmtx.h
+++ b/os/kernel/include/chmtx.h
@@ -28,10 +28,10 @@
 #ifndef _CHMTX_H_

 #define _CHMTX_H_

 

-#if CH_USE_MUTEXES

+#if CH_USE_MUTEXES || defined(__DOXYGEN__)

 

 /**

- * @brief Mutex structure.

+ * @brief   Mutex structure.

  */

 typedef struct Mutex {

   ThreadsQueue          m_queue;    /**< @brief Queue of the threads sleeping

diff --git a/os/kernel/include/chqueues.h b/os/kernel/include/chqueues.h
index 3e4078461..c18da0fc7 100644
--- a/os/kernel/include/chqueues.h
+++ b/os/kernel/include/chqueues.h
@@ -28,7 +28,7 @@
 #ifndef _CHQUEUES_H_

 #define _CHQUEUES_H_

 

-#if CH_USE_QUEUES

+#if CH_USE_QUEUES || defined(__DOXYGEN__)

 

 /*

  * Module dependencies check.

diff --git a/os/kernel/include/chregistry.h b/os/kernel/include/chregistry.h
index 956482a57..f9185acb7 100644
--- a/os/kernel/include/chregistry.h
+++ b/os/kernel/include/chregistry.h
@@ -28,7 +28,7 @@
 #ifndef _CHREGISTRY_H_

 #define _CHREGISTRY_H_

 

-#if CH_USE_REGISTRY

+#if CH_USE_REGISTRY || defined(__DOXYGEN__)

 

 /**

  * @brief   Removes a thread from the registry list.

diff --git a/os/kernel/include/chsem.h b/os/kernel/include/chsem.h
index 02ad3a79f..cf0897675 100644
--- a/os/kernel/include/chsem.h
+++ b/os/kernel/include/chsem.h
@@ -28,7 +28,7 @@
 #ifndef _CHSEM_H_

 #define _CHSEM_H_

 

-#if CH_USE_SEMAPHORES

+#if CH_USE_SEMAPHORES || defined(__DOXYGEN__)

 

 /**

  * @brief   Semaphore structure.