From 2891f7d645c4be187ac96ee4011207531d25c34a Mon Sep 17 00:00:00 2001 From: gdisirio Date: Mon, 4 Oct 2010 17:16:18 +0000 Subject: 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 --- os/hal/include/can.h | 2 ++ os/hal/include/mac.h | 6 ++++++ os/hal/include/mmc_spi.h | 12 +++++++++++ os/hal/include/pal.h | 29 +++++++++++++++++++++++++ os/hal/include/pwm.h | 4 ++++ os/hal/include/serial.h | 56 +++++++++++++++++++++++++++++++++++------------- 6 files changed, 94 insertions(+), 15 deletions(-) (limited to 'os/hal/include') 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)) -- cgit v1.2.3