From 80a8621ec04e3fa9588ad09cbf0f1b6da1429776 Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Wed, 11 Mar 2009 09:22:59 +0000
Subject: Documentation improvements.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@830 35acf78f-673a-0410-8e92-d51de3d6d3f4
---
 src/chdebug.c    |   8 ++---
 src/chheap.c     |  16 ++++-----
 src/chlists.c    |  20 +++++------
 src/chmempools.c |  19 +++++-----
 src/chmsg.c      |  18 +++++-----
 src/chmtx.c      |  24 ++++++-------
 src/chqueues.c   | 106 +++++++++++++++++++++++++++++--------------------------
 src/chschd.c     |   2 +-
 src/chsem.c      |   1 +
 src/chserial.c   |  84 +++++++++++++++++++++++--------------------
 src/chsys.c      |  20 +++++------
 11 files changed, 164 insertions(+), 154 deletions(-)

(limited to 'src')

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