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

os/hal/include/adc.h

@@ -20,6 +20,7 @@
 /**
  * @file    adc.h
  * @brief   ADC Driver macros and structures.
+ *
  * @addtogroup ADC
  * @{
  */

os/hal/include/can.h

@@ -20,6 +20,7 @@
 /**
  * @file    can.h
  * @brief   CAN Driver macros and structures.
+ *
  * @addtogroup CAN
  * @{
  */

os/hal/include/hal.h

@@ -20,6 +20,7 @@
 /**
  * @file    hal.h
  * @brief   HAL subsystem header.
+ *
  * @addtogroup HAL
  * @{
  */

os/hal/include/mac.h

@@ -71,9 +71,10 @@
  * @param[in] tdp       pointer to a @p MACTransmitDescriptor structure
  * @param[in] buf       pointer to the buffer containing the data to be written
  * @param[in] size      number of bytes to be written
- * @return The number of bytes written into the descriptor's stream, this
+ * @return              The number of bytes written into the descriptor's
- *         value can be less than the amount specified in the parameter
+ *                      stream, this value can be less than the amount
- *         @p size if the maximum frame size is reached.
+ *                      specified in the parameter @p size if the maximum frame
+ *                      size is reached.
  */
 #define macWriteTransmitDescriptor(tdp, buf, size)                          \
     mac_lld_write_transmit_descriptor(tdp, buf, size)
@@ -85,8 +86,8 @@
  * @param[in] buf   pointer to the buffer that will receive the read data
  * @param[in] size  number of bytes to be read
  * @return          The number of bytes read from the descriptor's stream, this
- *         value can be less than the amount specified in the parameter
+ *                  value can be less than the amount specified in the
- *         @p size if there are no more bytes to read.
+ *                  parameter @p size if there are no more bytes to read.
  */
 #define macReadReceiveDescriptor(rdp, buf, size)                            \
     mac_lld_read_receive_descriptor(rdp, buf, size)

os/hal/include/mii.h

@@ -25,6 +25,7 @@
 /*-*
  * @file    mii.h
  * @brief   MII Driver macros and structures.
+ *
  * @addtogroup MII
  * @{
  */

os/hal/include/mmc_spi.h

@@ -20,6 +20,7 @@
 /**
  * @file    mmc_spi.h
  * @brief   MMC over SPI driver header.
+ *
  * @addtogroup MMC_SPI
  * @{
  */

os/hal/include/pal.h

@@ -20,6 +20,7 @@
 /**
  * @file    pal.h
  * @brief   I/O Ports Abstraction Layer macros, types and structures.
+ *
  * @addtogroup PAL
  * @{
  */
@@ -119,12 +120,19 @@
  *          not belonging to the bus.
  */
 typedef struct {
-  /** Port identifier.*/
+  /**
+   * @brief Port identifier.
+   */
   ioportid_t            bus_portid;
-  /** Bus mask aligned to port bit 0. The bus mask implicitly define the bus
+  /**
-      width. A logical AND is performed on the bus data.*/
+   * @brief Bus mask aligned to port bit 0.
+   * @note  The bus mask implicitly define the bus width. A logical AND is
+   *        performed on the bus data.
+   */
   ioportmask_t          bus_mask;
-  /** Offset, within the port, of the least significant bit of the bus.*/
+  /**
+   * @brief Offset, within the port, of the least significant bit of the bus.
+   */
   uint_fast8_t          bus_offset;
 } IOBus;
 
@@ -156,10 +164,10 @@ typedef struct {
  * @details This macro should be used when statically initializing an I/O bus
  *          that is part of a bigger structure.
  *
- * @param name the name of the IOBus variable
+ * @param[in] name      the name of the IOBus variable
- * @param port the I/O port descriptor
+ * @param[in] port      the I/O port descriptor
- * @param width the bus width in bits
+ * @param[in] width     the bus width in bits
- * @param offset the bus bit offset within the port
+ * @param[in] offset    the bus bit offset within the port
  */
 #define _IOBUS_DATA(name, port, width, offset)                          \
   {port, PAL_GROUP_MASK(width), offset}
@@ -167,10 +175,10 @@ typedef struct {
 /**
  * @brief   Static I/O bus initializer.
  *
- * @param name the name of the IOBus variable
+ * @param[in] name      the name of the IOBus variable
- * @param port the I/O port descriptor
+ * @param[in] port      the I/O port descriptor
- * @param width the bus width in bits
+ * @param[in] width     the bus width in bits
- * @param offset the bus bit offset within the port
+ * @param[in] offset    the bus bit offset within the port
  */
 #define IOBUS_DECL(name, port, width, offset)                           \
   IOBus name = _IOBUS_DATA(name, port, width, offset)
@@ -186,12 +194,11 @@ typedef struct {
 
 /**
  * @brief   Reads the physical I/O port states.
+ * @note    The default implementation always return zero and computes the
+ *          parameter eventual side effects.
  *
  * @param[in] port      the port identifier
  * @return              The port logical states.
- *
- * @note The default implementation always return zero and computes the
- *       parameter eventual side effects.
  */
 #if !defined(pal_lld_readport) || defined(__DOXYGEN__)
 #define palReadPort(port) ((void)(port), 0)
@@ -203,12 +210,11 @@ typedef struct {
  * @brief   Reads the output latch.
  * @details The purpose of this function is to read back the latched output
  *          value.
+ * @note    The default implementation always return zero and computes the
+ *          parameter eventual side effects.
  *
  * @param[in] port      the port identifier
  * @return              The latched logical states.
- *
- * @note The default implementation always return zero and computes the
- *       parameter eventual side effects.
  */
 #if !defined(pal_lld_readlatch) || defined(__DOXYGEN__)
 #define palReadLatch(port) ((void)(port), 0)
@@ -218,12 +224,11 @@ typedef struct {
 
 /**
  * @brief   Writes a bits mask on a I/O port.
+ * @note    The default implementation does nothing except computing the
+ *          parameters eventual side effects.
  *
  * @param[in] port      the port identifier
  * @param[in] bits      the bits to be written on the specified port
- *
- * @note The default implementation does nothing except computing the
- *       parameters eventual side effects.
  */
 #if !defined(pal_lld_writeport) || defined(__DOXYGEN__)
 #define palWritePort(port, bits) ((void)(port), (void)(bits))
@@ -233,16 +238,16 @@ typedef struct {
 
 /**
  * @brief   Sets a bits mask on a I/O port.
- *
+ * @note    The operation is not guaranteed to be atomic on all the
- * @param[in] port the port identifier
+ *          architectures, for atomicity and/or portability reasons you may
- * @param[in] bits the bits to be ORed on the specified port
+ *          need to enclose port I/O operations between @p chSysLock() and
- *
+ *          @p chSysUnlock().
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
  * @note    The default implementation is non atomic and not necessarily
  *          optimal. Low level drivers may  optimize the function by using
  *          specific hardware or coding.
+ *
+ * @param[in] port      the port identifier
+ * @param[in] bits      the bits to be ORed on the specified port
  */
 #if !defined(pal_lld_setport) || defined(__DOXYGEN__)
 #define palSetPort(port, bits) {                                        \
@@ -254,16 +259,17 @@ typedef struct {
 
 /**
  * @brief   Clears a bits mask on a I/O port.
+ * @note    The operation is not guaranteed to be atomic on all the
+ *          architectures,  for atomicity and/or portability reasons you may
+ *          need to enclose port I/O operations between @p chSysLock() and
+ *          @p chSysUnlock().
+ * @note    The default implementation is non atomic and not necessarily
+ *          optimal. Low level drivers may  optimize the function by using
+ *          specific hardware or coding.
  *
  * @param[in] port      the port identifier
  * @param[in] bits      the bits to be cleared on the specified port
  *
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
- * @note The default implementation is non atomic and not necessarily
- *       optimal. Low level drivers may  optimize the function by using
- *       specific hardware or coding.
  */
 #if !defined(pal_lld_clearport) || defined(__DOXYGEN__)
 #define palClearPort(port, bits) {                                      \
@@ -275,16 +281,16 @@ typedef struct {
 
 /**
  * @brief   Toggles a bits mask on a I/O port.
- *
+ * @note    The operation is not guaranteed to be atomic on all the
- * @param[in] port the port identifier
+ *          architectures, for atomicity and/or portability reasons you may
- * @param[in] bits the bits to be XORed on the specified port
+ *          need to enclose port I/O operations between @p chSysLock() and
- *
+ *          @p chSysUnlock().
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
  * @note    The default implementation is non atomic and not necessarily
  *          optimal. Low level drivers may  optimize the function by using
  *          specific hardware or coding.
+ *
+ * @param[in] port      the port identifier
+ * @param[in] bits      the bits to be XORed on the specified port
  */
 #if !defined(pal_lld_toggleport) || defined(__DOXYGEN__)
 #define palTogglePort(port, bits) {                                     \
@@ -314,11 +320,11 @@ typedef struct {
  * @brief   Writes a group of bits.
  *
  * @param[in] port      the port identifier
- * @param[in] mask the group mask, a logical AND is performed on the output
+ * @param[in] mask      the group mask, a logical AND is performed on the
- *            data
+ *                      output  data
  * @param[in] offset    the group bit offset within the port
- * @param[in] bits the bits to be written. Values exceeding the group width
+ * @param[in] bits      the bits to be written. Values exceeding the group
- *            are masked.
+ *                      width are masked.
  */
 #if !defined(pal_lld_writegroup) || defined(__DOXYGEN__)
 #define palWriteGroup(port, mask, offset, bits) {                       \
@@ -335,12 +341,12 @@ typedef struct {
  * @brief   Pads group mode setup.
  * @details This function programs a pads group belonging to the same port
  *          with the specified mode.
+ * @note    Programming an unknown or unsupported mode is silently ignored.
  *
  * @param[in] port      the port identifier
  * @param[in] mask      the group mask
  * @param[in] mode      the setup mode
  *
- * @note Programming an unknown or unsupported mode is silently ignored.
  */
 #if !defined(pal_lld_setgroupmode) || defined(__DOXYGEN__)
 #define palSetGroupMode(port, mask, mode)
@@ -350,16 +356,17 @@ typedef struct {
 
 /**
  * @brief   Reads an input pad logical state.
+ * @note    The default implementation not necessarily optimal. Low level
+ *          drivers may  optimize the function by using specific hardware
+ *          or coding.
+ * @note    The default implementation internally uses the @p palReadPort().
  *
  * @param[in] port      the port identifier
  * @param[in] pad       the pad number within the port
  * @return              The logical state.
- * @retval 0 low logical state.
+ * @retval PAL_LOW      low logical state.
- * @retval 1 high logical state.
+ * @retval PAL_HIGH     high logical state.
  *
- * @note The default implementation not necessarily optimal. Low level drivers
- *       may  optimize the function by using specific hardware or coding.
- * @note The default implementation internally uses the @p palReadPort().
  */
 #if !defined(pal_lld_readpad) || defined(__DOXYGEN__)
 #define palReadPad(port, pad) ((palReadPort(port) >> (pad)) & 1)
@@ -369,19 +376,19 @@ typedef struct {
 
 /**
  * @brief   Writes a logical state on an output pad.
+ * @note    The operation is not guaranteed to be atomic on all the
+ *          architectures, for atomicity and/or portability reasons you may
+ *          need to enclose port I/O operations between @p chSysLock() and
+ *          @p chSysUnlock().
+ * @note    The default implementation is non atomic and not necessarily
+ *          optimal. Low level drivers may  optimize the function by using
+ *          specific hardware or coding.
+ * @note    The default implementation internally uses the @p palReadLatch()
+ *          and @p palWritePort().
  *
  * @param[in] port      the port identifier
  * @param[in] pad       the pad number within the port
  * @param[out] bit      the logical value, the value must be @p 0 or @p 1
- *
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
- * @note The default implementation is non atomic and not necessarily
- *       optimal. Low level drivers may  optimize the function by using
- *       specific hardware or coding.
- * @note The default implementation internally uses the @p palReadLatch() and
- *       @p palWritePort().
  */
 #if !defined(pal_lld_writepad) || defined(__DOXYGEN__)
 #define palWritePad(port, pad, bit) {                                   \
@@ -393,18 +400,18 @@ typedef struct {
 #endif
 
 /**
- * @brief Sets a pad logical state to @p 1.
+ * @brief   Sets a pad logical state to @p PAL_HIGH.
- *
+ * @note    The operation is not guaranteed to be atomic on all the
- * @param[in] port the port identifier
+ *          architectures, for atomicity and/or portability reasons you may
- * @param[in] pad the pad number within the port
+ *          need to enclose port I/O operations between @p chSysLock() and
- *
+ *          @p chSysUnlock().
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
  * @note    The default implementation is non atomic and not necessarily
  *          optimal. Low level drivers may  optimize the function by using
  *          specific hardware or coding.
  * @note    The default implementation internally uses the @p palSetPort().
+ *
+ * @param[in] port      the port identifier
+ * @param[in] pad       the pad number within the port
  */
 #if !defined(pal_lld_setpad) || defined(__DOXYGEN__)
 #define palSetPad(port, pad) palSetPort(port, PAL_PORT_BIT(pad))
@@ -413,18 +420,18 @@ typedef struct {
 #endif
 
 /**
- * @brief Clears a pad logical state to @p 0.
+ * @brief   Clears a pad logical state to @p PAL_LOW.
- *
+ * @note    The operation is not guaranteed to be atomic on all the
- * @param[in] port the port identifier
+ *          architectures, for atomicity and/or portability reasons you may
- * @param[in] pad the pad number within the port
+ *          need to enclose port I/O operations between @p chSysLock() and
- *
+ *          @p chSysUnlock().
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
  * @note    The default implementation is non atomic and not necessarily
  *          optimal. Low level drivers may  optimize the function by using
  *          specific hardware or coding.
  * @note    The default implementation internally uses the @p palClearPort().
+ *
+ * @param[in] port      the port identifier
+ * @param[in] pad       the pad number within the port
  */
 #if !defined(pal_lld_clearpad) || defined(__DOXYGEN__)
 #define palClearPad(port, pad) palClearPort(port, PAL_PORT_BIT(pad))
@@ -434,17 +441,17 @@ typedef struct {
 
 /**
  * @brief   Toggles a pad logical state.
- *
+ * @note    The operation is not guaranteed to be atomic on all the
- * @param[in] port the port identifier
+ *          architectures, for atomicity and/or portability reasons you may
- * @param[in] pad the pad number within the port
+ *          need to enclose port I/O operations between @p chSysLock() and
- *
+ *          @p chSysUnlock().
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
  * @note    The default implementation is non atomic and not necessarily
  *          optimal. Low level drivers may  optimize the function by using
  *          specific hardware or coding.
  * @note    The default implementation internally uses the @p palTogglePort().
+ *
+ * @param[in] port      the port identifier
+ * @param[in] pad       the pad number within the port
  */
 #if !defined(pal_lld_togglepad) || defined(__DOXYGEN__)
 #define palTogglePad(port, pad) palTogglePort(port, PAL_PORT_BIT(pad))
@@ -456,14 +463,14 @@ typedef struct {
 /**
  * @brief   Pad mode setup.
  * @details This function programs a pad with the specified mode.
+ * @note    The default implementation not necessarily optimal. Low level
+ *          drivers may  optimize the function by using specific hardware
+ *          or coding.
+ * @note    Programming an unknown or unsupported mode is silently ignored.
  *
  * @param[in] port      the port identifier
  * @param[in] pad       the pad number within the port
  * @param[in] mode      the setup mode
- *
- * @note The default implementation not necessarily optimal. Low level drivers
- *       may  optimize the function by using specific hardware or coding.
- * @note Programming an unknown or unsupported mode is silently ignored.
  */
 #if !defined(pal_lld_setpadmode) || defined(__DOXYGEN__)
 #define palSetPadMode(port, pad, mode)                                  \

os/hal/include/pwm.h

@@ -20,6 +20,7 @@
 /**
  * @file    pwm.h
  * @brief   PWM Driver macros and structures.
+ *
  * @addtogroup PWM
  * @{
  */

os/hal/include/serial.h

@@ -20,6 +20,7 @@
 /**
  * @file    serial.h
  * @brief   Serial Driver macros and structures.
+ *
  * @addtogroup SERIAL
  * @{
  */
@@ -67,7 +68,8 @@
  * @brief   Serial buffers size.
  * @details Configuration parameter, you can change the depth of the queue
  *          buffers depending on the requirements of your application.
- * @note The default is 64 bytes for both the transmission and receive buffers.
+ * @note    The default is 64 bytes for both the transmission and receive
+ *          buffers.
  */
 #if !defined(SERIAL_BUFFERS_SIZE) || defined(__DOXYGEN__)
 #define SERIAL_BUFFERS_SIZE         64
@@ -122,9 +124,7 @@ struct SerialDriverVMT {
  *          I/O queues.
  */
 struct _SerialDriver {
-  /**
+  /** @brief Virtual Methods Table.*/
-   * Virtual Methods Table.
-   */
   const struct SerialDriverVMT *vmt;
   _serial_driver_data
 };
@@ -138,6 +138,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          checks directly the output queue. This is faster but cannot
  *          be used to check different channels implementations.
+ *
  * @see     chIOPutWouldBlock()
  */
 #define sdPutWouldBlock(sdp) chOQIsFull(&(sdp)->oqueue)
@@ -147,6 +148,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          checks directly the input queue. This is faster but cannot
  *          be used to check different channels implementations.
+ *
  * @see     chIOGetWouldBlock()
  */
 #define sdGetWouldBlock(sdp) chIQIsEmpty(&(sdp)->iqueue)
@@ -156,6 +158,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          writes directly on the output queue. This is faster but cannot
  *          be used to write to different channels implementations.
+ *
  * @see     chIOPut()
  */
 #define sdPut(sdp, b) chOQPut(&(sdp)->oqueue, b)
@@ -165,6 +168,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          writes directly on the output queue. This is faster but cannot
  *          be used to write to different channels implementations.
+ *
  * @see     chIOPutTimeout()
  */
 #define sdPutTimeout(sdp, b, t) chOQPutTimeout(&(sdp)->iqueue, b, t)
@@ -174,6 +178,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          reads directly from the input queue. This is faster but cannot
  *          be used to read from different channels implementations.
+ *
  * @see     chIOGet()
  */
 #define sdGet(sdp) chIQGet(&(sdp)->iqueue)
@@ -183,6 +188,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          reads directly from the input queue. This is faster but cannot
  *          be used to read from different channels implementations.
+ *
  * @see     chIOGetTimeout()
  */
 #define sdGetTimeout(sdp, t) chIQGetTimeout(&(sdp)->iqueue, t)
@@ -192,6 +198,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          writes directly to the output queue. This is faster but cannot
  *          be used to write from different channels implementations.
+ *
  * @see     chIOWriteTimeout()
  */
 #define sdWrite(sdp, b, n)                                                  \
@@ -203,6 +210,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          writes directly to the output queue. This is faster but cannot
  *          be used to write from different channels implementations.
+ *
  * @see     chIOWriteTimeout()
  */
 #define sdWriteTimeout(sdp, b, n, t)                                        \
@@ -213,6 +221,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          writes directly to the output queue. This is faster but cannot
  *          be used to write from different channels implementations.
+ *
  * @see     chIOWriteTimeout()
  */
 #define sdAsynchronousWrite(sdp, b, n)                                      \
@@ -223,6 +232,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          reads directly from the input queue. This is faster but cannot
  *          be used to read from different channels implementations.
+ *
  * @see     chIOReadTimeout()
  */
 #define sdRead(sdp, b, n)                                                   \
@@ -234,6 +244,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          reads directly from the input queue. This is faster but cannot
  *          be used to read from different channels implementations.
+ *
  * @see     chIOReadTimeout()
  */
 #define sdReadTimeout(sdp, b, n, t)                                         \
@@ -244,6 +255,7 @@ struct _SerialDriver {
  * @details This function bypasses the indirect access to the channel and
  *          reads directly from the input queue. This is faster but cannot
  *          be used to read from different channels implementations.
+ *
  * @see     chIOReadTimeout()
  */
 #define sdAsynchronousRead(sdp, b, n)                                       \

os/hal/include/spi.h

@@ -20,6 +20,7 @@
 /**
  * @file    spi.h
  * @brief   SPI Driver macros and structures.
+ *
  * @addtogroup SPI
  * @{
  */

os/hal/src/adc.c

@@ -20,6 +20,7 @@
 /**
  * @file    adc.c
  * @brief   ADC Driver code.
+ *
  * @addtogroup ADC
  * @{
  */
@@ -122,6 +123,10 @@ void adcStop(ADCDriver *adcp) {
  *            time. This kind of conversion can only be stopped by explicitly
  *            invoking @p adcStopConversion().
  *          .
+ * @note    The buffer is organized as a matrix of M*N elements where M is the
+ *          channels number configured into the conversion group and N is the
+ *          buffer depth. The samples are sequentially written into the buffer
+ *          with no gaps.
  *
  * @param[in] adcp      pointer to the @p ADCDriver object
  * @param[in] grpp      pointer to a @p ADCConversionGroup object
@@ -132,11 +137,6 @@ void adcStop(ADCDriver *adcp) {
  * @return              The operation status.
  * @retval FALSE        the conversion has been started.
  * @retval TRUE         the driver is busy, conversion not started.
- *
- * @note The buffer is organized as a matrix of M*N elements where M is the
- *       channels number configured into the conversion group and N is the
- *       buffer depth. The samples are sequentially written into the buffer
- *       with no gaps.
  */
 bool_t adcStartConversion(ADCDriver *adcp,
                           const ADCConversionGroup *grpp,

os/hal/src/can.c

@@ -18,8 +18,9 @@
 */
 
 /**
- * @file CAN.c
+ * @file    can.c
  * @brief   CAN Driver code.
+ *
  * @addtogroup CAN
  * @{
  */
@@ -177,7 +178,8 @@ msg_t canTransmit(CANDriver *canp, const CANTxFrame *ctfp, systime_t timeout) {
  * @return              The operation result.
  * @retval RDY_OK       a frame has been received and placed in the buffer.
  * @retval RDY_TIMEOUT  operation not finished within the specified time or
- *         frame not immediately available if invoked using @p TIME_IMMEDIATE.
+ *                      frame not immediately available if invoked using
+ *                      @p TIME_IMMEDIATE.
  * @retval RDY_RESET    driver stopped while waiting.
  */
 msg_t canReceive(CANDriver *canp, CANRxFrame *crfp, systime_t timeout) {
@@ -204,7 +206,6 @@ msg_t canReceive(CANDriver *canp, CANRxFrame *crfp, systime_t timeout) {
  * @brief   Returns the current status mask and clears it.
  *
  * @param[in] canp      pointer to the @p CANDriver object
- *
  * @return              The status flags mask.
  */
 canstatus_t canGetAndClearFlags(CANDriver *canp) {
@@ -242,8 +243,8 @@ void canSleep(CANDriver *canp) {
 
 /**
  * @brief   Enforces leaving the sleep mode.
- * @note The sleep mode is supposed to be usually exited automatically by an
+ * @note    The sleep mode is supposed to be usually exited automatically by
- *       hardware event.
+ *          an hardware event.
  *
  * @param[in] canp      pointer to the @p CANDriver object
  */

os/hal/src/hal.c

@@ -20,6 +20,7 @@
 /**
  * @file    hal.c
  * @brief   HAL subsystem code.
+ *
  * @addtogroup HAL
  * @{
  */

os/hal/src/mac.c

@@ -20,6 +20,7 @@
 /**
  * @file    mac.c
  * @brief   MAC Driver code.
+ *
  * @addtogroup MAC
  * @{
  */
@@ -73,14 +74,14 @@ void macObjectInit(MACDriver *macp) {
 
 /**
  * @brief   MAC address setup.
- *
- * @param[in] macp pointer to the @p MACDriver object
- * @param[in] p pointer to a six bytes buffer containing the MAC address. If
- *            this parameter is set to @p NULL then a system default MAC is
- *            used.
- *
  * @note    This function must be invoked only with the driver in the stopped
  *          state. If invoked on an active interface then it is ignored.
+ *
+ * @param[in] macp      pointer to the @p MACDriver object
+ * @param[in] p         pointer to a six bytes buffer containing the MAC
+ *                      address. If this parameter is set to @p NULL then MAC
+ *                      a system default is used.
+ *
  */
 void macSetAddress(MACDriver *macp, const uint8_t *p) {
 

os/hal/src/mmc_spi.c

@@ -20,6 +20,7 @@
 /**
  * @file    mmc_spi.c
  * @brief   MMC over SPI driver code.
+ *
  * @addtogroup MMC_SPI
  * @{
  */
@@ -41,6 +42,11 @@
 /* Driver local functions.                                                   */
 /*===========================================================================*/
 
+/**
+ * @brief   Inserion monitor timer callback function.
+ *
+ * @param[in] p         pointer to the @p MMCDriver object
+ */
 void tmrfunc(void *p) {
   MMCDriver *mmcp = p;
 
@@ -116,7 +122,6 @@ static void send_hdr(MMCDriver *mmcp, uint8_t cmd, uint32_t arg) {
  * @brief   Receives a single byte response.
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
- *
  * @return              The response as an @p uint8_t value.
  * @retval 0xFF         timed out.
  */
@@ -138,7 +143,6 @@ static uint8_t recvr1(MMCDriver *mmcp) {
  * @param[in] mmcp      pointer to the @p MMCDriver object
  * @param cmd[in]       the command id
  * @param arg[in]       the command argument
- *
  * @return              The response as an @p uint8_t value.
  * @retval 0xFF         timed out.
  */
@@ -261,7 +265,6 @@ void mmcStop(MMCDriver *mmcp) {
  *          handler.
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
- *
  * @return              The operation status.
  * @retval FALSE        the operation was successful and the driver is now
  *                      in the @p MMC_READY state.
@@ -367,7 +370,6 @@ bool_t mmcDisconnect(MMCDriver *mmcp) {
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
  * @param[in] startblk  first block to read
- *
  * @return              The operation status.
  * @retval FALSE        the operation was successful.
  * @retval TRUE         the operation failed.
@@ -402,7 +404,6 @@ bool_t mmcStartSequentialRead(MMCDriver *mmcp, uint32_t startblk) {
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
  * @param[out] buffer   pointer to the read buffer
- *
  * @return              The operation status.
  * @retval FALSE        the operation was successful.
  * @retval TRUE         the operation failed.
@@ -441,7 +442,6 @@ bool_t mmcSequentialRead(MMCDriver *mmcp, uint8_t *buffer) {
  * @brief   Stops a sequential read gracefully.
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
- *
  * @return              The operation status.
  * @retval FALSE        the operation was successful.
  * @retval TRUE         the operation failed.
@@ -475,7 +475,6 @@ bool_t mmcStopSequentialRead(MMCDriver *mmcp) {
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
  * @param[in] startblk  first block to write
- *
  * @return              The operation status.
  * @retval FALSE        the operation was successful.
  * @retval TRUE         the operation failed.
@@ -510,7 +509,6 @@ bool_t mmcStartSequentialWrite(MMCDriver *mmcp, uint32_t startblk) {
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
  * @param[out] buffer   pointer to the write buffer
- *
  * @return              The operation status.
  * @retval FALSE        the operation was successful.
  * @retval TRUE         the operation failed.
@@ -548,7 +546,6 @@ bool_t mmcSequentialWrite(MMCDriver *mmcp, const uint8_t *buffer) {
  * @brief   Stops a sequential write gracefully.
  *
  * @param[in] mmcp      pointer to the @p MMCDriver object
- *
  * @return              The operation status.
  * @retval FALSE        the operation was successful.
  * @retval TRUE         the operation failed.

os/hal/src/pal.c

@@ -20,6 +20,7 @@
 /**
  * @file    pal.c
  * @brief   I/O Ports Abstraction Layer code.
+ *
  * @addtogroup PAL
  * @{
  */
@@ -47,16 +48,16 @@
 
 /**
  * @brief   Read from an I/O bus.
+ * @note    The operation is not guaranteed to be atomic on all the
+ *          architectures, for atomicity and/or portability reasons you may
+ *          need to enclose port I/O operations between @p chSysLock() and
+ *          @p chSysUnlock().
+ * @note    The function internally uses the @p palReadGroup() macro. The use
+ *          of this function is preferred when you value code size, readability
+ *          and error checking over speed.
  *
  * @param[in] bus       the I/O bus, pointer to a @p IOBus structure
  * @return              The bus logical states.
- *
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
- * @note The function internally uses the @p palReadGroup() macro. The use of
- *       this function is preferred when you value code size, readability  and
- *       error checking over speed.
  */
 ioportmask_t palReadBus(IOBus *bus) {
 
@@ -68,17 +69,18 @@ ioportmask_t palReadBus(IOBus *bus) {
 
 /**
  * @brief   Write to an I/O bus.
- *
+ * @note    The operation is not guaranteed to be atomic on all the
- * @param[in] bus the I/O bus, pointer to a @p IOBus structure
+ *          architectures, for atomicity and/or portability reasons you may
- * @param[in] bits the bits to be written on the I/O bus. Values exceeding
+ *          need to enclose port I/O operations between @p chSysLock() and
- *            the bus width are masked so most significant bits are lost.
+ *          @p chSysUnlock().
- *
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
  * @note    The default implementation is non atomic and not necessarily
  *          optimal. Low level drivers may  optimize the function by using
  *          specific hardware or coding.
+ *
+ * @param[in] bus       the I/O bus, pointer to a @p IOBus structure
+ * @param[in] bits      the bits to be written on the I/O bus. Values exceeding
+ *                      the bus width are masked so most significant bits are
+ *                      lost.
  */
 void palWriteBus(IOBus *bus, ioportmask_t bits) {
 
@@ -90,16 +92,16 @@ void palWriteBus(IOBus *bus, ioportmask_t bits) {
 
 /**
  * @brief   Programs a bus with the specified mode.
- *
+ * @note    The operation is not guaranteed to be atomic on all the
- * @param[in] bus the I/O bus, pointer to a @p IOBus structure
+ *          architectures, for atomicity and/or portability reasons you may
- * @param[in] mode the mode
+ *          need to enclose port I/O operations between @p chSysLock() and
- *
+ *          @p chSysUnlock().
- * @note The operation is not guaranteed to be atomic on all the architectures,
- *       for atomicity and/or portability reasons you may need to enclose port
- *       I/O operations between @p chSysLock() and @p chSysUnlock().
  * @note    The default implementation is non atomic and not necessarily
  *          optimal. Low level drivers may  optimize the function by using
  *          specific hardware or coding.
+ *
+ * @param[in] bus       the I/O bus, pointer to a @p IOBus structure
+ * @param[in] mode      the mode
  */
 void palSetBusMode(IOBus *bus, uint_fast8_t mode) {
 

os/hal/src/pwm.c

@@ -18,7 +18,7 @@
 */
 
 /**
- * @file PWM.c
+ * @file    pwm.c
  * @brief   PWM Driver code.
  * @addtogroup PWM
  * @{

os/hal/src/serial.c

@@ -20,6 +20,7 @@
 /**
  * @file    serial.c
  * @brief   Serial Driver code.
+ *
  * @addtogroup SERIAL
  * @{
  */
@@ -208,8 +209,8 @@ void sdIncomingDataI(SerialDriver *sdp, uint8_t b) {
  *
  * @param[in] sdp       pointer to a @p SerialDriver 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
+ * @retval Q_EMPTY      if the queue is empty (the lower driver usually
- *                 the interrupt source when this happens).
+ *                      disables the interrupt source when this happens).
  */
 msg_t sdRequestDataI(SerialDriver *sdp) {
   msg_t  b;
@@ -242,8 +243,8 @@ void sdAddFlagsI(SerialDriver *sdp, sdflags_t mask) {
  * @brief   Returns and clears the errors mask associated to the driver.
  *
  * @param[in] sdp       pointer to a @p SerialDriver structure
- * @return The condition flags modified since last time this function was
+ * @return              The condition flags modified since last time this
- *         invoked.
+ *                      function was invoked.
  */
 sdflags_t sdGetAndClearFlags(SerialDriver *sdp) {
   sdflags_t mask;

os/hal/src/spi.c

@@ -20,6 +20,7 @@
 /**
  * @file    spi.c
  * @brief   SPI Driver code.
+ *
  * @addtogroup SPI
  * @{
  */
@@ -168,14 +169,13 @@ void spiIgnore(SPIDriver *spip, size_t n) {
 /**
  * @brief   Exchanges data on the SPI bus.
  * @details This function performs a simultaneous transmit/receive operation.
+ * @note    The buffers are organized as uint8_t arrays for data sizes below
+ *          or equal to 8 bits else it is organized as uint16_t arrays.
  *
  * @param[in] spip      pointer to the @p SPIDriver object
  * @param[in] n         number of words to be exchanged
  * @param[in] txbuf     the pointer to the transmit buffer
  * @param[out] rxbuf    the pointer to the receive buffer
- *
- * @note The buffers are organized as uint8_t arrays for data sizes below or
- *       equal to 8 bits else it is organized as uint16_t arrays.
  */
 void spiExchange(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf) {
 
@@ -190,13 +190,12 @@ void spiExchange(SPIDriver *spip, size_t n, const void *txbuf, void *rxbuf) {
 
 /**
  * @brief   Sends data ever the SPI bus.
+ * @note    The buffers are organized as uint8_t arrays for data sizes below
+ *          or equal to 8 bits else it is organized as uint16_t arrays.
  *
  * @param[in] spip      pointer to the @p SPIDriver object
  * @param[in] n         number of words to send
  * @param[in] txbuf     the pointer to the transmit buffer
- *
- * @note The buffers are organized as uint8_t arrays for data sizes below or
- *       equal to 8 bits else it is organized as uint16_t arrays.
  */
 void spiSend(SPIDriver *spip, size_t n, const void *txbuf) {
 
@@ -211,13 +210,12 @@ void spiSend(SPIDriver *spip, size_t n, const void *txbuf) {
 
 /**
  * @brief   Receives data from the SPI bus.
+ * @note    The buffers are organized as uint8_t arrays for data sizes below
+ *          or equal to 8 bits else it is organized as uint16_t arrays.
  *
  * @param[in] spip      pointer to the @p SPIDriver object
  * @param[in] n         number of words to receive
  * @param[out] rxbuf    the pointer to the receive buffer
- *
- * @note The buffers are organized as uint8_t arrays for data sizes below or
- *       equal to 8 bits else it is organized as uint16_t arrays.
  */
 void spiReceive(SPIDriver *spip, size_t n, void *rxbuf) {
 
@@ -235,11 +233,11 @@ void spiReceive(SPIDriver *spip, size_t n, void *rxbuf) {
  * @brief   Gains exclusive access to the SPI bus.
  * @details This function tries to gain ownership to the SPI bus, if the bus
  *          is already being used then the invoking thread is queued.
+ * @note    This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION
+ *          option is set to @p TRUE.
  *
  * @param[in] spip      pointer to the @p SPIDriver object
  *
- * @note This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION
- *       option is set to @p TRUE.
  */
 void spiAcquireBus(SPIDriver *spip) {
 
@@ -254,11 +252,10 @@ void spiAcquireBus(SPIDriver *spip) {
 
 /**
  * @brief   Releases exclusive access to the SPI bus.
- *
- * @param[in] spip      pointer to the @p SPIDriver object
- *
  * @note    This function is only available when the @p SPI_USE_MUTUAL_EXCLUSION
  *          option is set to @p TRUE.
+ *
+ * @param[in] spip      pointer to the @p SPIDriver object
  */
 void spiReleaseBus(SPIDriver *spip) {
 

os/hal/templates/meta/driver.c

@@ -18,8 +18,9 @@
 */
 
 /**
- * @file XXX.c
+ * @file    xxx.c
  * @brief   XXX Driver code.
+ *
  * @addtogroup XXX
  * @{
  */

os/hal/templates/meta/driver.h

@@ -20,6 +20,7 @@
 /**
  * @file    xxx.h
  * @brief   XXX Driver macros and structures.
+ *
  * @addtogroup XXX
  * @{
  */

os/hal/templates/meta/driver_lld.c

@@ -20,6 +20,7 @@
 /**
  * @file    templates/xxx_lld.c
  * @brief   XXX Driver subsystem low level driver source template.
+ *
  * @addtogroup XXX_LLD
  * @{
  */

os/hal/templates/meta/driver_lld.h

@@ -20,6 +20,7 @@
 /**
  * @file    templates/xxx_lld.h
  * @brief   XXX Driver subsystem low level driver header template.
+ *
  * @addtogroup XXX_LLD
  * @{
  */