Documentation improvements, fixed a small error in the STM32 serial driver.

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

6 files changed, 94 insertions, 15 deletions

diff --git a/os/hal/include/can.h b/os/hal/include/can.h
index 4a40fb952..f87c57fee 100644
--- a/os/hal/include/can.h
+++ b/os/hal/include/can.h
@@ -100,6 +100,8 @@ typedef enum {
  *

  * @param[in] canp      pointer to the @p CANDriver object

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

+ *

+ * @iclass

  */

 #define canAddFlagsI(canp, mask) ((canp)->cd_status |= (mask))

 

diff --git a/os/hal/include/mac.h b/os/hal/include/mac.h
index a180cc4f0..ce6ca0add 100644
--- a/os/hal/include/mac.h
+++ b/os/hal/include/mac.h
@@ -60,6 +60,8 @@
  *

  * @param[in] macp      pointer to the @p MACDriver object

  * @return              The pointer to the @p EventSource structure.

+ *

+ * @api

  */

 #if CH_USE_EVENTS || defined(__DOXYGEN__)

 #define macGetReceiveEventSource(macp)  (&(macp)->md_rdevent)

@@ -75,6 +77,8 @@
  *                      stream, this value can be less than the amount

  *                      specified in the parameter @p size if the maximum frame

  *                      size is reached.

+ *

+ * @api

  */

 #define macWriteTransmitDescriptor(tdp, buf, size)                          \

     mac_lld_write_transmit_descriptor(tdp, buf, size)

@@ -88,6 +92,8 @@
  * @return          The number of bytes read from the descriptor's stream, this

  *                  value can be less than the amount specified in the

  *                  parameter @p size if there are no more bytes to read.

+ *

+ * @api

  */

 #define macReadReceiveDescriptor(rdp, buf, size)                            \

     mac_lld_read_receive_descriptor(rdp, buf, size)

diff --git a/os/hal/include/mmc_spi.h b/os/hal/include/mmc_spi.h
index cc698c3de..6af424d29 100644
--- a/os/hal/include/mmc_spi.h
+++ b/os/hal/include/mmc_spi.h
@@ -181,11 +181,23 @@ typedef struct {
 

 /**

  * @brief   Returns the driver state.

+ *

+ * @param[in] mmcp      pointer to the @p MMCDriver object

+ * @return              The driver state.

+ *

+ * @api

  */

 #define mmcGetDriverState(mmcp) ((mmcp)->mmc_state)

 

 /**

  * @brief   Returns the write protect status.

+ *

+ * @param[in] mmcp      pointer to the @p MMCDriver object

+ * @return              The card state.

+ * @retval FALSE        card not inserted.

+ * @retval TRUE         card inserted.

+ *

+ * @api

  */

 #define mmcIsWriteProtected(mmcp) ((mmcp)->mmc_is_protected())

 

diff --git a/os/hal/include/pal.h b/os/hal/include/pal.h
index 2530471eb..8e66eb522 100644
--- a/os/hal/include/pal.h
+++ b/os/hal/include/pal.h
@@ -189,6 +189,8 @@ typedef struct {
  * @param[in] config pointer to an architecture specific configuration

  *            structure. This structure is defined in the low level driver

  *            header.

+ *

+ * @init

  */

 #define palInit(config) pal_lld_init(config)

 

@@ -199,6 +201,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @return              The port logical states.

+ *

+ * @api

  */

 #if !defined(pal_lld_readport) || defined(__DOXYGEN__)

 #define palReadPort(port) ((void)(port), 0)

@@ -215,6 +219,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @return              The latched logical states.

+ *

+ * @api

  */

 #if !defined(pal_lld_readlatch) || defined(__DOXYGEN__)

 #define palReadLatch(port) ((void)(port), 0)

@@ -229,6 +235,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @param[in] bits      bits to be written on the specified port

+ *

+ * @api

  */

 #if !defined(pal_lld_writeport) || defined(__DOXYGEN__)

 #define palWritePort(port, bits) ((void)(port), (void)(bits))

@@ -248,6 +256,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @param[in] bits      bits to be ORed on the specified port

+ *

+ * @api

  */

 #if !defined(pal_lld_setport) || defined(__DOXYGEN__)

 #define palSetPort(port, bits) {                                        \

@@ -270,6 +280,7 @@ typedef struct {
  * @param[in] port      port identifier

  * @param[in] bits      bits to be cleared on the specified port

  *

+ * @api

  */

 #if !defined(pal_lld_clearport) || defined(__DOXYGEN__)

 #define palClearPort(port, bits) {                                      \

@@ -291,6 +302,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @param[in] bits      bits to be XORed on the specified port

+ *

+ * @api

  */

 #if !defined(pal_lld_toggleport) || defined(__DOXYGEN__)

 #define palTogglePort(port, bits) {                                     \

@@ -308,6 +321,8 @@ typedef struct {
  *                      data

  * @param[in] offset    group bit offset within the port

  * @return              The group logical states.

+ *

+ * @api

  */

 #if !defined(pal_lld_readgroup) || defined(__DOXYGEN__)

 #define palReadGroup(port, mask, offset)                               \

@@ -325,6 +340,8 @@ typedef struct {
  * @param[in] offset    group bit offset within the port

  * @param[in] bits      bits to be written. Values exceeding the group

  *                      width are masked.

+ *

+ * @api

  */

 #if !defined(pal_lld_writegroup) || defined(__DOXYGEN__)

 #define palWriteGroup(port, mask, offset, bits) {                       \

@@ -347,6 +364,7 @@ typedef struct {
  * @param[in] mask      group mask

  * @param[in] mode      group mode

  *

+ * @api

  */

 #if !defined(pal_lld_setgroupmode) || defined(__DOXYGEN__)

 #define palSetGroupMode(port, mask, mode)

@@ -367,6 +385,7 @@ typedef struct {
  * @retval PAL_LOW      low logical state.

  * @retval PAL_HIGH     high logical state.

  *

+ * @api

  */

 #if !defined(pal_lld_readpad) || defined(__DOXYGEN__)

 #define palReadPad(port, pad) ((palReadPort(port) >> (pad)) & 1)

@@ -390,6 +409,8 @@ typedef struct {
  * @param[in] pad       pad number within the port

  * @param[in] bit       logical value, the value must be @p PAL_LOW or

  *                      @p PAL_HIGH

+ *

+ * @api

  */

 #if !defined(pal_lld_writepad) || defined(__DOXYGEN__)

 #define palWritePad(port, pad, bit) {                                   \

@@ -413,6 +434,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @param[in] pad       pad number within the port

+ *

+ * @api

  */

 #if !defined(pal_lld_setpad) || defined(__DOXYGEN__)

 #define palSetPad(port, pad) palSetPort(port, PAL_PORT_BIT(pad))

@@ -433,6 +456,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @param[in] pad       pad number within the port

+ *

+ * @api

  */

 #if !defined(pal_lld_clearpad) || defined(__DOXYGEN__)

 #define palClearPad(port, pad) palClearPort(port, PAL_PORT_BIT(pad))

@@ -453,6 +478,8 @@ typedef struct {
  *

  * @param[in] port      port identifier

  * @param[in] pad       pad number within the port

+ *

+ * @api

  */

 #if !defined(pal_lld_togglepad) || defined(__DOXYGEN__)

 #define palTogglePad(port, pad) palTogglePort(port, PAL_PORT_BIT(pad))

@@ -472,6 +499,8 @@ typedef struct {
  * @param[in] port      port identifier

  * @param[in] pad       pad number within the port

  * @param[in] mode      pad mode

+ *

+ * @api

  */

 #if !defined(pal_lld_setpadmode) || defined(__DOXYGEN__)

 #define palSetPadMode(port, pad, mode)                                  \

diff --git a/os/hal/include/pwm.h b/os/hal/include/pwm.h
index 562be26bc..12fe2b6ad 100644
--- a/os/hal/include/pwm.h
+++ b/os/hal/include/pwm.h
@@ -86,6 +86,8 @@ typedef void (*pwmcallback_t)(void);
  * @param[in] pwmp      pointer to a @p PWMDriver object

  * @param[in] channel   PWM channel identifier

  * @param[in] width     PWM pulse width as clock pulses number

+ *

+ * @iclass

  */

 #define pwmEnableChannelI(pwmp, channel, width) {                           \

   pwm_lld_enable_channel(pwmp, channel, width);                             \

@@ -99,6 +101,8 @@ typedef void (*pwmcallback_t)(void);
  *

  * @param[in] pwmp      pointer to a @p PWMDriver object

  * @param[in] channel   PWM channel identifier

+ *

+ * @iclass

  */

 #define pwmDisableChannelI(pwmp, channel) {                                 \

   pwm_lld_disable_channel(pwmp, channel);                                   \

diff --git a/os/hal/include/serial.h b/os/hal/include/serial.h
index 74969308f..6b4f05688 100644
--- a/os/hal/include/serial.h
+++ b/os/hal/include/serial.h
@@ -135,71 +135,85 @@ struct SerialDriver {
 

 /**

  * @brief   Direct output check on a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdPutWouldBlock(sdp) chOQIsFull(&(sdp)->oqueue)

 

 /**

  * @brief   Direct input check on a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdGetWouldBlock(sdp) chIQIsEmpty(&(sdp)->iqueue)

 

 /**

  * @brief   Direct write to a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdPut(sdp, b) chOQPut(&(sdp)->oqueue, b)

 

 /**

  * @brief   Direct write to a @p SerialDriver with timeout specification.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdPutTimeout(sdp, b, t) chOQPutTimeout(&(sdp)->iqueue, b, t)

 

 /**

  * @brief   Direct read from a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdGet(sdp) chIQGet(&(sdp)->iqueue)

 

 /**

  * @brief   Direct read from a @p SerialDriver with timeout specification.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdGetTimeout(sdp, t) chIQGetTimeout(&(sdp)->iqueue, t)

 

 /**

  * @brief   Direct blocking write to a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdWrite(sdp, b, n)                                                  \

   chOQWriteTimeout(&(sdp)->oqueue, b, n, TIME_INFINITE)

@@ -207,33 +221,39 @@ struct SerialDriver {
 /**

  * @brief   Direct blocking write to a @p SerialDriver with timeout

  *          specification.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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.

+ *          be used to write to different channels implementations.

  *

  * @see     chIOWriteTimeout()

+ *

+ * @api

  */

 #define sdWriteTimeout(sdp, b, n, t)                                        \

   chOQWriteTimeout(&(sdp)->oqueue, b, n, t)

 

 /**

  * @brief   Direct non-blocking write to a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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.

+ *          be used to write to different channels implementations.

  *

  * @see     chIOWriteTimeout()

+ *

+ * @api

  */

 #define sdAsynchronousWrite(sdp, b, n)                                      \

   chOQWriteTimeout(&(sdp)->oqueue, b, n, TIME_IMMEDIATE)

 

 /**

  * @brief   Direct blocking read from a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdRead(sdp, b, n)                                                   \

   chIQReadTimeout(&(sdp)->iqueue, b, n, TIME_INFINITE)

@@ -241,22 +261,26 @@ struct SerialDriver {
 /**

  * @brief   Direct blocking read from a @p SerialDriver with timeout

  *          specification.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdReadTimeout(sdp, b, n, t)                                         \

   chIQReadTimeout(&(sdp)->iqueue, b, n, t)

 

 /**

  * @brief   Direct non-blocking read from a @p SerialDriver.

- * @details This function bypasses the indirect access to the channel and

+ * @note    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()

+ *

+ * @api

  */

 #define sdAsynchronousRead(sdp, b, n)                                       \

   chIQReadTimeout(&(sdp)->iqueue, b, n, TIME_IMMEDIATE)

@@ -265,10 +289,12 @@ struct SerialDriver {
  * @brief   Returns the status change event source.

  * @details The status change event source is broadcasted when the channel

  *          status is updated, the status flags can then be fetched and

- *          cheared by using @p sdGetAndClearFlags().

+ *          cleared by using @p sdGetAndClearFlags().

  *

  * @param[in] ip        pointer to a @p SerialDriver object

  * @return              A pointer to an @p EventSource object.

+ *

+ * @api

  */

 #define sdGetStatusChangeEventSource(ip) (&((ip)->vmt->sevent))