Documentation improvements.

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

12 files changed, 166 insertions, 155 deletions

diff --git a/readme.txt b/readme.txt
index 7607cc93d..c938f3dff 100644
--- a/readme.txt
+++ b/readme.txt
@@ -83,7 +83,8 @@ Win32-MinGW            - ChibiOS/RT simulator and demo into a WIN32 process,
 - FIX: Removed unused chSysPuts() macro (bug 2672678).

 - FIX: Renamed function chSysInTimeWindow() as chTimeIsWithin() and renamed

   the macro chSysGetTime() in chTimeNow(), the old names are still recognized

-  but marked as deprecated (fixes the bug 2678953 but goes a bit further).

+  but marked as deprecated (fixes the bug 2678953 but goes a bit further by

+  introducing a new API category "Time").

 - Removed testcond.c|h and moved the test cases into testmtx.c. Mutexes and

   condvars have to be tested together.

 - Added architecture diagram to the documentation.

diff --git a/src/chdebug.c b/src/chdebug.c
index c8dba33e6..dc16a27bc 100644
--- a/src/chdebug.c
+++ b/src/chdebug.c
@@ -44,8 +44,8 @@ void trace_init(void) {
 /**

  * @brief Inserts in the circular debug trace buffer a context switch record.

  *

- * @param otp the thread being switched out

- * @param ntp the thread to be resumed

+ * @param[in] otp the thread being switched out

+ * @param[in] ntp the thread to be resumed

  */

 void chDbgTrace(Thread *otp, Thread *ntp) {

 

@@ -62,14 +62,14 @@ void chDbgTrace(Thread *otp, Thread *ntp) {
 /**

  * @brief Pointer to the panic message.

  * @details This pointer is meant to be accessed through the debugger, it is

- * written once and then the system is halted.
+ *          written once and then the system is halted.
  */

 char *panic_msg;

 

 /**

  * @brief Prints a panic message on the console and then halts the system.

  *

- * @param msg the pointer to the panic message string

+ * @param[in] msg the pointer to the panic message string

  */

 void chDbgPanic(char *msg) {

 

diff --git a/src/chheap.c b/src/chheap.c
index adfe2842f..82b1ba785 100644
--- a/src/chheap.c
+++ b/src/chheap.c
@@ -95,13 +95,13 @@ void heap_init(void) {
 

 /**

  * @brief Allocates a block of memory from the heap by using the first-fit

- * algorithm.

+ *        algorithm.

  * @details The allocated block is guaranteed to be properly aligned for a

- * pointer data type.

+ *          pointer data type.

  *

- * @param size the size of the block to be allocated. Note that the allocated

- *             block may be a bit bigger than the requested size for alignment

- *             and fragmentation reasons.

+ * @param[in] size the size of the block to be allocated. Note that the

+ *                 allocated block may be a bit bigger than the requested

+ *                 size for alignment and fragmentation reasons.

  * @return A pointer to the allocated block.

  * @retval NULL if the block cannot be allocated.

  */

@@ -148,7 +148,7 @@ void *chHeapAlloc(size_t size) {
 /**

  * @brief Frees a previously allocated memory block.

  *

- * @param p the memory block pointer

+ * @param[in] p the memory block pointer

  */

 void chHeapFree(void *p) {

   struct header *qp, *hp;

@@ -195,8 +195,8 @@ void chHeapFree(void *p) {
 /**

  * @brief Reports the heap status.

  *

- * @param sizep pointer to a variable that will receive the total fragmented

- *              free space

+ * @param[in] sizep pointer to a variable that will receive the total

+ *                  fragmented free space

  * @return The number of fragments in the heap.

  * @note This function is meant to be used in the test suite, it should not be

  *       really useful for the application code.

diff --git a/src/chlists.c b/src/chlists.c
index 39bea02cc..a3ec568a0 100644
--- a/src/chlists.c
+++ b/src/chlists.c
@@ -29,8 +29,8 @@
 /**

  * @brief Inserts a thread into a priority ordered queue.

  *

- * @param tp the pointer to the thread to be inserted in the list

- * @param tqp the pointer to the threads list header

+ * @param[in] tp the pointer to the thread to be inserted in the list

+ * @param[in] tqp the pointer to the threads list header

  * @note The insertion is done by scanning the list from the highest priority

  *       toward the lowest.

  * @note This function is @b not an API.

@@ -52,8 +52,8 @@ void prio_insert(Thread *tp, ThreadsQueue *tqp) {
 /**

  * @brief Inserts a Thread into a queue.

  *

- * @param tp the pointer to the thread to be inserted in the list

- * @param tqp the pointer to the threads list header

+ * @param[in] tp the pointer to the thread to be inserted in the list

+ * @param[in] tqp the pointer to the threads list header

  * @note This function is @b not an API.

  */

 void queue_insert(Thread *tp, ThreadsQueue *tqp) {

@@ -65,7 +65,7 @@ void queue_insert(Thread *tp, ThreadsQueue *tqp) {
 /**

  * @brief Removes the first-out Thread from a queue and returns it.

  *

- * @param tqp the pointer to the threads list header

+ * @param[in] tqp the pointer to the threads list header

  * @return The removed thread pointer.

  * @note This function is @b not an API.

  */

@@ -79,7 +79,7 @@ Thread *fifo_remove(ThreadsQueue *tqp) {
 /**

  * @brief Removes the last-out Thread from a queue and returns it.

  *

- * @param tqp the pointer to the threads list header

+ * @param[in] tqp the pointer to the threads list header

  * @return The removed thread pointer.

  * @note This function is @b not an API.

  */

@@ -93,7 +93,7 @@ Thread *lifo_remove(ThreadsQueue *tqp) {
 /**

  * @brief Removes a Thread from a FIFO list and returns it.

  *

- * @param tp the pointer to the thread to be removed from the list

+ * @param[in] tp the pointer to the thread to be removed from the list

  * @return The removed thread pointer.

  * @note This function is @b not an API.

  */

@@ -107,8 +107,8 @@ Thread *dequeue(Thread *tp) {
 /**

  * @brief Pushes a Thread on top of a stack list.

  *

- * @param tp the pointer to the thread to be inserted in the list

- * @param tlp the pointer to the threads list header

+ * @param[in] tp the pointer to the thread to be inserted in the list

+ * @param[in] tlp the pointer to the threads list header

  * @note This function is @b not an API.

  */

 void list_insert(Thread *tp, ThreadsList *tlp) {

@@ -120,7 +120,7 @@ void list_insert(Thread *tp, ThreadsList *tlp) {
 /**

  * @brief Pops a Thread from the top of a stack list and returns it.

  *

- * @param tlp the pointer to the threads list header

+ * @param[in] tlp the pointer to the threads list header

  * @return The removed thread pointer.

  * @note The list must be non-empty before calling this function.

  * @note This function is @b not an API.

diff --git a/src/chmempools.c b/src/chmempools.c
index 7d3a162bb..dd6f3d1ba 100644
--- a/src/chmempools.c
+++ b/src/chmempools.c
@@ -27,12 +27,12 @@
 #include <ch.h>

 

 #if CH_USE_MEMPOOLS

-

 /**

  * @brief Initializes an empty memory pool.

  *

- * @param mp pointer to a @p MemoryPool structure

- * @param size the size of the objects contained in this memory pool

+ * @param[out] mp pointer to a @p MemoryPool structure

+ * @param[in] size the size of the objects contained in this memory pool,

+ *                 the minimum accepted size is the size of a pointer to void

  */

 void chPoolInit(MemoryPool *mp, size_t size) {

 

@@ -45,7 +45,7 @@ void chPoolInit(MemoryPool *mp, size_t size) {
 /**

  * @brief Allocates an object from a memory pool.

  *

- * @param mp pointer to a @p MemoryPool structure

+ * @param[in] mp pointer to a @p MemoryPool structure

  * @return The pointer to the allocated object.

  * @retval NULL if pool is empty.

  */

@@ -63,7 +63,7 @@ void *chPoolAllocI(MemoryPool *mp) {
 /**

  * @brief Allocates an object from a memory pool.

  *

- * @param mp pointer to a @p MemoryPool structure

+ * @param[in] mp pointer to a @p MemoryPool structure

  * @return The pointer to the allocated object.

  * @retval NULL if pool is empty.

  */

@@ -79,8 +79,8 @@ void *chPoolAlloc(MemoryPool *mp) {
 /**

  * @brief Releases (or adds) an object into (to) a memory pool.

  *

- * @param mp pointer to a @p MemoryPool structure

- * @param objp the pointer to the object to be released or added

+ * @param[in] mp pointer to a @p MemoryPool structure

+ * @param[in] objp the pointer to the object to be released or added

  * @note the object is assumed to be of the right size for the specified

  *       memory pool.

  */

@@ -96,8 +96,8 @@ void chPoolFreeI(MemoryPool *mp, void *objp) {
 /**

  * @brief Releases (or adds) an object into (to) a memory pool.

  *

- * @param mp pointer to a @p MemoryPool structure

- * @param objp the pointer to the object to be released or added

+ * @param[in] mp pointer to a @p MemoryPool structure

+ * @param[in] objp the pointer to the object to be released or added

  * @note the object is assumed to be of the right size for the specified

  *       memory pool.

  */

@@ -107,7 +107,6 @@ void chPoolFree(MemoryPool *mp, void *objp) {
   chPoolFreeI(mp, objp);

   chSysUnlock();

 }

-

 #endif /* CH_USE_MEMPOOLS */

 

 /** @} */

diff --git a/src/chmsg.c b/src/chmsg.c
index 6744b7ac9..c506b6847 100644
--- a/src/chmsg.c
+++ b/src/chmsg.c
@@ -37,10 +37,10 @@
 /**

  * @brief Sends a message to the specified thread.

  * @details The sender is stopped until the receiver executes a

- * @p chMsgRelease()after receiving the message.

+ *          @p chMsgRelease()after receiving the message.

  *

- * @param tp the pointer to the thread

- * @param msg the message

+ * @param[in] tp the pointer to the thread

+ * @param[in] msg the message

  * @return The return message from @p chMsgRelease().

  */

 msg_t chMsgSend(Thread *tp, msg_t msg) {

@@ -62,13 +62,13 @@ msg_t chMsgSend(Thread *tp, msg_t msg) {
 #if CH_USE_EVENTS && CH_USE_MESSAGES_EVENT

 /**

  * @brief Sends a message to the specified thread and atomically pends an

- * events set.

+ *        events set.

  * @details The sender is stopped until the receiver executes a

- * @p chMsgRelease() after receiving the message.

+ *          @p chMsgRelease() after receiving the message.

  *

- * @param tp the pointer to the thread

- * @param msg the message

- * @param mask the event flags set to be pended

+ * @param[in] tp the pointer to the thread

+ * @param[in] msg the message

+ * @param[in] mask the event flags set to be pended

  * @return The return message from @p chMsgRelease().

  * @note This function assumes that the receiving thread is not sleeping into

  *       a @p chMsgWait(). The use case is that the server thread is waiting

@@ -136,7 +136,7 @@ msg_t chMsgGet(void) {
 /**

  * @brief Releases the thread waiting on top of the messages queue.

  *

- * @param msg the message returned to the message sender

+ * @param[in] msg the message returned to the message sender

  * @note You can call this function only if there is a message already in the

  *       queue else the result will be unpredictable (a crash most likely).

  *       Exiting from the @p chMsgWait() ensures you have at least one

diff --git a/src/chmtx.c b/src/chmtx.c
index b1d32d220..5fcb6fd5e 100644
--- a/src/chmtx.c
+++ b/src/chmtx.c
@@ -31,7 +31,7 @@
 /**
  * @brief Initializes s @p Mutex structure.
  *
- * @param mp pointer to a @p Mutex structure
+ * @param[out] mp pointer to a @p Mutex structure
  * @note This function can be invoked from within an interrupt handler even if
  *       it is not an I-Class API because it does not touch any critical kernel
  *       data structure.
@@ -47,7 +47,7 @@ void chMtxInit(Mutex *mp) {
 /**
  * @brief Locks the specified mutex.
  *
- * @param mp pointer to the @p Mutex structure
+ * @param[in] mp pointer to the @p Mutex structure
  */
 void chMtxLock(Mutex *mp) {
 
@@ -61,7 +61,7 @@ void chMtxLock(Mutex *mp) {
 /**
  * @brief Locks the specified mutex.
  *
- * @param mp pointer to the @p Mutex structure
+ * @param[in] mp pointer to the @p Mutex structure
  * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
  *       block.
  */
@@ -136,10 +136,10 @@ void chMtxLockS(Mutex *mp) {
 /**
  * @brief Tries to lock a mutex.
  * @details This function does not have any overhead related to
- * the priority inheritance mechanism because it does not try to enter a sleep
- * state on the mutex.
+ *          the priority inheritance mechanism because it does not try to
+ *          enter a sleep state on the mutex.
  *
- * @param mp pointer to the @p Mutex structure
+ * @param[in] mp pointer to the @p Mutex structure
  * @retval TRUE if the mutex was successfully acquired
  * @retval FALSE if the lock attempt failed.
  */
@@ -157,9 +157,9 @@ bool_t chMtxTryLock(Mutex *mp) {
 /**
  * @brief Tries to lock a mutex.
  * @details This function does not have any overhead related to
- * the priority inheritance mechanism because it does not try to enter a sleep
- * state on the mutex.
- * @param mp pointer to the @p Mutex structure
+ *          the priority inheritance mechanism because it does not try to
+ *          enter a sleep state on the mutex.
+ * @param[in] mp pointer to the @p Mutex structure
  * @retval TRUE if the mutex was successfully acquired
  * @retval FALSE if the lock attempt failed.
  * @note This function must be called within a @p chSysLock() / @p chSysUnlock()
@@ -273,9 +273,9 @@ Mutex *chMtxUnlockS(void) {
 /**
  * @brief Unlocks all the mutexes owned by the invoking thread.
  * @details This function is <b>MUCH MORE</b> efficient than releasing the
- * mutexes one by one and not just because the call overhead, this function
- * does not have any overhead related to the priority inheritance mechanism
- * too.
+ *          mutexes one by one and not just because the call overhead,
+ *          this function does not have any overhead related to the priority
+ *          inheritance mechanism.
  */
 void chMtxUnlockAll(void) {
 
diff --git a/src/chqueues.c b/src/chqueues.c
index 6dcc61af6..b7e14e69d 100644
--- a/src/chqueues.c
+++ b/src/chqueues.c
@@ -31,13 +31,14 @@
 /**

  * @brief Initializes an input queue.

  * @details A Semaphore is internally initialized and works as a counter of

- * the bytes contained in the queue.

+ *          the bytes contained in the queue.

  *

- * @param qp pointer to a @p Queue structure

- * @param buffer pointer to a memory area allocated as queue buffer

- * @param size size of the queue buffer

- * @param inotify pointer to a callback function that is invoked when

- *        some data is read from the Queue. The value can be @p NULL.

+ * @param[out] qp pointer to a @p Queue structure

+ * @param[in] buffer pointer to a memory area allocated as queue buffer

+ * @param[in] size size of the queue buffer

+ * @param[in] inotify pointer to a callback function that is invoked when

+ *                    some data is read from the Queue. The value can be

+*                     @p NULL.

  */

 void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {

 

@@ -51,7 +52,7 @@ void chIQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t inotify) {
  * @brief Resets an input queue.

  * @details All the data is lost and the waiting threads resumed.

  *

- * @param qp pointer to a @p Queue structure

+ * @param[in] qp pointer to a @p Queue structure

  */

 void chIQReset(Queue *qp) {

 

@@ -66,8 +67,8 @@ void chIQReset(Queue *qp) {
 /**

  * @brief Inserts a byte into an input queue.

  *

- * @param qp pointer to a @p Queue structure

- * @param b the byte value to be written

+ * @param[in] qp pointer to a @p Queue structure

+ * @param[in] b the byte value to be written

  * @retval Q_OK if the operation is successful.

  * @retval Q_FULL if the queue is full.

  * @note This function is the lower side endpoint of the Input Queue.

@@ -89,9 +90,9 @@ msg_t chIQPutI(Queue *qp, uint8_t b) {
 /**

  * @brief Gets a byte from the input queue.

  * @details If the queue is empty then the calling thread is suspended until

- * a byte arrives in the queue.

+ *          a byte arrives in the queue.

  *

- * @param qp pointer to a @p Queue structure

+ * @param[in] qp pointer to a @p Queue structure

  * @return A byte value from the queue.

  * @retval Q_RESET if the queue was reset.

  */

@@ -120,10 +121,10 @@ msg_t chIQGet(Queue *qp) {
 /**

  * @brief Gets a byte from the input queue.

  * @details If the queue is empty then the calling thread is suspended until

- * a byte arrives in the queue or the specified time expires.

+ *          a byte arrives in the queue or the specified time expires.

  *

- * @param qp pointer to a @p Queue structure

- * @param time the number of ticks before the operation timeouts

+ * @param[in] qp pointer to a @p Queue structure

+ * @param[in] time the number of ticks before the operation timeouts

  * @return A byte value from the queue.

  * @retval Q_TIMEOUT if the specified time expired.

  * @retval Q_RESET if the queue was reset.

@@ -156,11 +157,11 @@ msg_t chIQGetTimeout(Queue *qp, systime_t time) {
 /**

  * @brief Reads some data from the input queue into the specified buffer.

  * @details The function is non-blocking and can return zero if the queue is

- * empty.

+ *          empty.

  *

- * @param qp pointer to a @p Queue structure

- * @param buffer the data buffer

- * @param n the maximum amount of data to be read

+ * @param[in] qp pointer to a @p Queue structure

+ * @param[out] buffer the data buffer

+ * @param[in] n the maximum amount of data to be read

  * @return The number of bytes read.

  * @note This function is the upper side endpoint of the input queue.

  * @note The function is not atomic, if you need atomicity it is suggested

@@ -200,13 +201,14 @@ size_t chIQRead(Queue *qp, uint8_t *buffer, size_t n) {
 /**

  * @brief Initializes an output queue.

  * @details A Semaphore is internally initialized and works as a counter of the

- * free bytes in the queue.

+ *          free bytes in the queue.

  *

- * @param qp pointer to a @p Queue structure

- * @param buffer pointer to a memory area allocated as queue buffer

- * @param size size of the queue buffer

- * @param onotify pointer to a callback function that is invoked when

- *        some data is written in the Queue. The value can be @p NULL.

+ * @param[out] qp pointer to a @p Queue structure

+ * @param[in] buffer pointer to a memory area allocated as queue buffer

+ * @param[in] size size of the queue buffer

+ * @param[in] onotify pointer to a callback function that is invoked when

+ *                    some data is written in the Queue. The value can be

+ *                    @p NULL.

  */

 void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {

 

@@ -220,7 +222,7 @@ void chOQInit(Queue *qp, uint8_t *buffer, size_t size, qnotify_t onotify) {
  * @brief Resets an Output Queue.

  * @details All the data is lost and the waiting threads resumed.

  *

- * @param qp pointer to a @p Queue structure

+ * @param[in] qp pointer to a @p Queue structure

  */

 void chOQReset(Queue *qp) {

 

@@ -235,10 +237,10 @@ void chOQReset(Queue *qp) {
 /**

  * @brief Inserts a byte in the output queue.

  * @details If the queue is full then the thread is suspended until the queue

- * has free space available.

+ *          has free space available.

  *

- * @param qp pointer to a @p Queue structure

- * @param b the byte value to be written

+ * @param[in] qp pointer to a @p Queue structure

+ * @param[in] b the byte value to be written

  */

 void chOQPut(Queue *qp, uint8_t b) {

 

@@ -258,7 +260,7 @@ void chOQPut(Queue *qp, uint8_t b) {
 /**

  * @brief Gets a byte from an output queue.

  *

- * @param qp pointer to a @p Queue structure

+ * @param[in] qp pointer to a @p Queue structure

  * @return The byte value from the queue.

  * @retval Q_EMPTY if the queue is empty.

  * @note This function is the lower side endpoint of the output queue.

@@ -281,11 +283,11 @@ msg_t chOQGetI(Queue *qp) {
 /**

  * @brief Writes some data from the specified buffer into the queue.

  * @details The function is non-blocking and can return zero if the queue is

- * full.

+ *          full.

  *

- * @param qp pointer to a @p Queue structure

- * @param buffer the data buffer

- * @param n the maximum amount of data to be written

+ * @param[in] qp pointer to a @p Queue structure

+ * @param[in] buffer the data buffer

+ * @param[in] n the maximum amount of data to be written

  * @return The number of written bytes.

  * @note This function is the upper side endpoint of the output queue.

  * @note The function is not atomic, if you need atomicity it is suggested

@@ -327,13 +329,15 @@ size_t chOQWrite(Queue *qp, uint8_t *buffer, size_t n) {
  /**

  * @brief Initializes an half duplex queue.

  *

- * @param qp pointer to the @p HalfDuplexQueue structure

- * @param buffer pointer to a memory area allocated as buffer for the queue

- * @param size the size of the queue buffer

- * @param inotify pointer to a callback function that is invoked when

- *        some data is read from the queue. The value can be @p NULL.

- * @param onotify pointer to a callback function that is invoked when

- *        some data is written to the queue. The value can be @p NULL.

+ * @param[out] qp pointer to the @p HalfDuplexQueue structure

+ * @param[in] buffer pointer to a memory area allocated as buffer for the queue

+ * @param[in] size the size of the queue buffer

+ * @param[in] inotify pointer to a callback function that is invoked when

+ *                    some data is read from the queue. The value can be

+ *                    @p NULL.

+ * @param[in] onotify pointer to a callback function that is invoked when

+ *                    some data is written to the queue. The value can be

+ *                    @p NULL.

  */

 void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,

                qnotify_t inotify, qnotify_t onotify) {

@@ -349,9 +353,9 @@ void chHDQInit(HalfDuplexQueue *qp, uint8_t *buffer, size_t size,
 /**

  * @brief Reads a byte from the receive queue.

  * @details If the queue is empty or is in transmission mode then the invoking

- * thread is suspended.

+ *          thread is suspended.

  *

- * @param qp pointer to a @p HalfDuplexQueue structure

+ * @param[in] qp pointer to a @p HalfDuplexQueue structure

  * @return The byte value.

  * @retval Q_RESET if the queue was reset.

  */

@@ -384,10 +388,10 @@ msg_t chHDQGetReceive(HalfDuplexQueue *qp) {
 /**

  * @brief Reads a byte from the receive queue.

  * @details If the queue is empty or is in transmission mode then the invoking

- * thread is suspended.

+ *          thread is suspended.

  *

- * @param qp pointer to a @p HalfDuplexQueue structure

- * @param time the number of ticks before the operation timouts

+ * @param[in] qp pointer to a @p HalfDuplexQueue structure

+ * @param[in] time the number of ticks before the operation timouts

  * @return The byte value.

  * @retval Q_TIMEOUT if a timeout occurs.

  * @note The function is available only if the @p CH_USE_QUEUES_TIMEOUT and

@@ -423,10 +427,10 @@ msg_t chHDQGetReceiveTimeout(HalfDuplexQueue *qp, systime_t time) {
 /**

  * @brief Writes a byte into the transmit queue.

  * @details If the buffer contains unread input data then the the buffer is

- * cleared and the queue goes in transmission mode.

+ *          cleared and the queue goes in transmission mode.

  *

- * @param qp pointer to a @p HalfDuplexQueue structure

- * @param b the byte value to be written

+ * @param[in] qp pointer to a @p HalfDuplexQueue structure

+ * @param[in] b the byte value to be written

  */

 void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {

 

@@ -457,7 +461,7 @@ void chHDQPutTransmit(HalfDuplexQueue *qp, uint8_t b) {
 /**

  * @brief Gets a byte from the transmit queue.

  *

- * @param qp pointer to a @p HalfDuplexQueue structure

+ * @param[in] qp pointer to a @p HalfDuplexQueue structure

  * @return The byte value.

  * @retval Q_EMPTY if the transmit queue is empty (not in transmission mode).

  * @note This function must be called with interrupts disabled or from an

@@ -480,8 +484,8 @@ msg_t chHDQGetTransmitI(HalfDuplexQueue *qp) {
  * @brief Writes a byte into the receive queue.

  * @details If the queue is in transmission mode then the byte is lost.

  *

- * @param qp pointer to a @p HalfDuplexQueue structure

- * @param b the byte value to be written

+ * @param[in] qp pointer to a @p HalfDuplexQueue structure

+ * @param[in] b the byte value to be written

  * @retval Q_OK if the operation is successful.

  * @retval Q_FULL if the driver is in transmit mode or the receive queue is full.

  * @note This function must be called with interrupts disabled or from an

diff --git a/src/chschd.c b/src/chschd.c
index 4d094d786..b246d8f57 100644
--- a/src/chschd.c
+++ b/src/chschd.c
@@ -76,7 +76,7 @@ Thread *chSchReadyI(Thread *tp) {
  * @details The next highest priority thread becomes running. The threads
  *          states are described into @p threads.h.
  *
- * @param newstate the new thread state
+ * @param[in] newstate the new thread state
  * @note The function must be called in the system mutex zone.
  * @note The function is not meant to be used in the user code directly.
  */
diff --git a/src/chsem.c b/src/chsem.c
index 6c254e836..21f80c284 100644
--- a/src/chsem.c
+++ b/src/chsem.c
@@ -136,6 +136,7 @@ msg_t chSemWaitS(Semaphore *sp) {
  *             the following special values are allowed:

  *             - @a TIME_IMMEDIATE immediate timeout.

  *             - @a TIME_INFINITE no timeout.

+ *             .

  * @retval RDY_OK if the semaphore was signaled or not taken.

  * @retval RDY_RESET if the semaphore was reset using @p chSemReset().

  * @retval RDY_TIMEOUT if the semaphore was not signaled or reset within the

diff --git a/src/chserial.c b/src/chserial.c
index 67cb96bab..725df207d 100644
--- a/src/chserial.c
+++ b/src/chserial.c
@@ -30,17 +30,19 @@
 /**

  * @brief Initializes a generic full duplex driver.

  * @details The HW dependent part of the initialization has to be performed

- * outside, usually in the hardware initialization code.

+ *          outside, usually in the hardware initialization code.

  *

- * @param sd pointer to a @p FullDuplexDriver structure

- * @param ib pointer to a memory area allocated for the Input Queue buffer

- * @param isize size of the Input Queue buffer

- * @param inotify pointer to a callback function that is invoked when

- *        some data is read from the Queue. The value can be @p NULL.

- * @param ob pointer to a memory area allocated for the Output Queue buffer

- * @param osize size of the Output Queue buffer

- * @param onotify pointer to a callback function that is invoked when

- *        some data is written in the Queue. The value can be @p NULL.

+ * @param[out] sd pointer to a @p FullDuplexDriver structure

+ * @param[in] ib pointer to a memory area allocated for the Input Queue buffer

+ * @param[in] isize size of the Input Queue buffer

+ * @param[in] inotify pointer to a callback function that is invoked when

+ *                    some data is read from the Queue. The value can be

+ *                    @p NULL.

+ * @param[in] ob pointer to a memory area allocated for the Output Queue buffer

+ * @param[in] osize size of the Output Queue buffer

+ * @param[in] onotify pointer to a callback function that is invoked when

+ *                    some data is written in the Queue. The value can be

+ *                    @p NULL.

  */

 void chFDDInit(FullDuplexDriver *sd,

                uint8_t *ib, size_t isize, qnotify_t inotify,

@@ -60,9 +62,10 @@ void chFDDInit(FullDuplexDriver *sd,
 /**

  * @brief Handles incoming data.

  * @details This function must be called from the input interrupt service

- * routine in order to enqueue incoming data and generate the related events.

- * @param sd pointer to a @p FullDuplexDriver structure

- * @param b the byte to be written in the driver's Input Queue

+ *          routine in order to enqueue incoming data and generate the

+ *          related events.

+ * @param[in] sd pointer to a @p FullDuplexDriver structure

+ * @param[in] b the byte to be written in the driver's Input Queue

  */

 void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {

 

@@ -75,12 +78,12 @@ void chFDDIncomingDataI(FullDuplexDriver *sd, uint8_t b) {
 /**

  * @brief Handles outgoing data.

  * @details Must be called from the output interrupt service routine in order

- * to get the next byte to be transmitted.

+ *          to get the next byte to be transmitted.

  *

- * @param sd pointer to a @p FullDuplexDriver structure

+ * @param[in] sd pointer to a @p FullDuplexDriver structure

  * @return The byte value read from the driver's output queue.

  * @retval Q_EMPTY if the queue is empty (the lower driver usually disables

- *         the interrupt source when this happens).

+ *                 the interrupt source when this happens).

  */

 msg_t chFDDRequestDataI(FullDuplexDriver *sd) {

 

@@ -93,10 +96,10 @@ msg_t chFDDRequestDataI(FullDuplexDriver *sd) {
 /**

  * @brief Handles communication events/errors.

  * @details Must be called from the I/O interrupt service routine in order to

- * notify I/O conditions as errors, signals change etc.

+ *          notify I/O conditions as errors, signals change etc.

  *

- * @param sd pointer to a @p FullDuplexDriver structure

- * @param mask condition flags to be added to the mask

+ * @param[in] sd pointer to a @p FullDuplexDriver structure

+ * @param[in] mask condition flags to be added to the mask

  */

 void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {

 

@@ -107,7 +110,7 @@ void chFDDAddFlagsI(FullDuplexDriver *sd, dflags_t mask) {
 /**

  * @brief Returns and clears the errors mask associated to the driver.

  *

- * @param sd pointer to a @p FullDuplexDriver structure

+ * @param[in] sd pointer to a @p FullDuplexDriver structure

  * @return The condition flags modified since last time this function was

  *         invoked.

  */

@@ -124,15 +127,17 @@ dflags_t chFDDGetAndClearFlags(FullDuplexDriver *sd) {
 /**

  * @brief Initializes a generic half duplex driver.

  * @details The HW dependent part of the initialization has to be performed

- * outside, usually in the hardware initialization code.

+ *          outside, usually in the hardware initialization code.

  *

- * @param sd pointer to a @p HalfDuplexDriver structure

- * @param b pointer to a memory area allocated for the queue buffer

- * @param size the buffer size

- * @param inotify pointer to a callback function that is invoked when

- *        some data is read from the queue. The value can be @p NULL.

- * @param onotify pointer to a callback function that is invoked when

- *        some data is written in the queue. The value can be @p NULL.

+ * @param[out] sd pointer to a @p HalfDuplexDriver structure

+ * @param[in] b pointer to a memory area allocated for the queue buffer

+ * @param[in] size the buffer size

+ * @param[in] inotify pointer to a callback function that is invoked when

+ *                    some data is read from the queue. The value can be

+ *                    @p NULL.

+ * @param[in] onotify pointer to a callback function that is invoked when

+ *                    some data is written in the queue. The value can be

+ *                    @p NULL.

  */

 void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,

                qnotify_t inotify, qnotify_t onotify) {

@@ -149,9 +154,10 @@ void chHDDInit(HalfDuplexDriver *sd, uint8_t *b, size_t size,
 /**

  * @brief Handles incoming data.

  * @details This function must be called from the input interrupt service

- * routine in order to enqueue incoming data and generate the related events.

- * @param sd pointer to a @p FullDuplexDriver structure

- * @param b the byte to be written in the driver's input queue

+ *          routine in order to enqueue incoming data and generate the

+ *          related events.

+ * @param[in] sd pointer to a @p FullDuplexDriver structure

+ * @param[in] b the byte to be written in the driver's input queue

  */

 void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {

 

@@ -163,13 +169,13 @@ void chHDDIncomingDataI(HalfDuplexDriver *sd, uint8_t b) {
 

 /**

  * @brief Handles outgoing data.

- * @brief Must be called from the output interrupt service routine in order

- * to get the next byte to be transmitted.

+ * @details Must be called from the output interrupt service routine in order

+ *          to get the next byte to be transmitted.

  *

- * @param sd pointer to a @p HalfDuplexDriver structure

+ * @param[in] sd pointer to a @p HalfDuplexDriver structure

  * @return The byte value read from the driver's output queue.

  * @retval Q_EMPTY if the queue is empty (the lower driver usually disables

- *         the interrupt source when this happens).

+ *                 the interrupt source when this happens).

  */

 msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {

 

@@ -182,10 +188,10 @@ msg_t chHDDRequestDataI(HalfDuplexDriver *sd) {
 /**

  * @brief Handles communication events/errors.

  * @details Must be called from the I/O interrupt service routine in order to

- * notify I/O conditions as errors, signals change etc.

+ *          notify I/O conditions as errors, signals change etc.

  *

- * @param sd pointer to a @p HalfDuplexDriver structure

- * @param mask condition flags to be added to the mask

+ * @param[in] sd pointer to a @p HalfDuplexDriver structure

+ * @param[in] mask condition flags to be added to the mask

  */

 void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {

 

@@ -196,7 +202,7 @@ void chHDDAddFlagsI(HalfDuplexDriver *sd, dflags_t mask) {
 /**

  * @brief Returns and clears the errors mask associated to the driver.

  *

- * @param sd pointer to a @p HalfDuplexDriver structure

+ * @param[in] sd pointer to a @p HalfDuplexDriver structure

  * @return The condition flags modified since last time this function was

  *         invoked.

  */

diff --git a/src/chsys.c b/src/chsys.c
index 666d0cfef..cedd3d28b 100644
--- a/src/chsys.c
+++ b/src/chsys.c
@@ -31,13 +31,12 @@ static WORKING_AREA(idle_thread_wa, IDLE_THREAD_STACK_SIZE);
 /**
  * @brief This function implements the idle thread infinite loop.
  * @details The function puts the processor in the lowest power mode capable
- * to serve interrupts.<br>
- * The priority is internally set to the minimum system value so that this
- * thread is executed only if there are no other ready threads in the system.
+ *          to serve interrupts.<br>
+ *          The priority is internally set to the minimum system value so
+ *          that this thread is executed only if there are no other ready
+ *          threads in the system.
  *
- * @param p the thread parameter, unused in this scenario
- * @note Implementation should declare this function as a weak symbol in order
- *       to allow applications to re-implement it.
+ * @param[in] p the thread parameter, unused in this scenario
  */
 static void idle_thread(void *p) {
 
@@ -50,7 +49,7 @@ static void idle_thread(void *p) {
 /**
  * @brief ChibiOS/RT initialization.
  * @details After executing this function the current instructions stream
- * becomes the main thread.
+ *          becomes the main thread.
  *
  * @note Interrupts should be still disabled when @p chSysInit() is invoked
  *       and are internally enabled.
@@ -88,10 +87,11 @@ void chSysInit(void) {
 /**
  * @brief Handles time ticks for round robin preemption and timer increments.
  * @details Decrements the remaining time quantum of the running thread
- * and preempts it when the quantum is used up. Increments system time and
- * manages the timers.
+ *          and preempts it when the quantum is used up. Increments system
+ *          time and manages the timers.
+ *
  * @note The frequency of the timer determines the system tick granularity and,
- * together with the @p CH_TIME_QUANTUM macro, the round robin interval.
+ *       together with the @p CH_TIME_QUANTUM macro, the round robin interval.
  */
 void chSysTimerHandlerI(void) {