From 9ffea7e261ec4016d788abbbf7c4a6d3a78e0a04 Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Sat, 18 Sep 2010 06:48:56 +0000
Subject: Documentation improvements, renamed some event APIs.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@2179 35acf78f-673a-0410-8e92-d51de3d6d3f4
---
 os/kernel/include/chbsem.h     |  2 +-
 os/kernel/include/chcond.h     |  2 +-
 os/kernel/include/chdebug.h    |  6 +++---
 os/kernel/include/chevents.h   | 16 +++++++++-------
 os/kernel/include/chheap.h     |  2 +-
 os/kernel/include/chmboxes.h   | 13 ++++++++-----
 os/kernel/include/chmemcore.h  |  2 +-
 os/kernel/include/chmempools.h |  2 +-
 os/kernel/include/chmsg.h      |  2 +-
 os/kernel/include/chmtx.h      |  4 ++--
 os/kernel/include/chqueues.h   |  2 +-
 os/kernel/include/chregistry.h |  2 +-
 os/kernel/include/chsem.h      |  2 +-
 13 files changed, 31 insertions(+), 26 deletions(-)

(limited to 'os/kernel/include')

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.
-- 
cgit v1.2.3