TI 官方库的注释风格挺实用的

一目了然, 蛮好看的, 那就拿来自己用试试. 

################################################################################################################

/** ===========================================================================
 *   @func CSL_spiOpen
 *
 *   @desc
 *        This function populates the peripheral data object for the instance
 *        and returns a handle to the instance.
 *        The open call sets up the data structures for the particular instance
 *        of SPI device. The device can be re-opened anytime after it has been
 *        normally closed if so required. SPI Hardware setup will be performed
 *        at the end of the open call only if the HwSetup Pointer supplied was
 *        non-NULL. The handle returned by this call is input as an essential
 *        argument for rest of the APIs described for this module.
 *
 *   @arg pSpiObj
 *        Pointer to the SPI instance object
 *
 *   @arg spiNum
 *        Instance of the SPI to be opened.
 *
 *   @arg pSpiParam
 *        Pointer to module specific parameters
 *
 *   @arg pStatus
 *        pointer for returning status of the function call
 *
 *   @ret CSL_SpiHandle
 *        Valid SPI instance handle will be returned if status value is
 *        equal to CSL_SOK.
 *
 *   @eg
 *        CSL_Status        status;
 *        CSL_SpiObj        spiObj;
 *        CSL_SpiHandle     hSpi;
 *
 *        hSpi = CSL_spiOpen (&spiObj,
 *                            CSL_SPI_0,
 *                            NULL,
 *                            &status
 *                            );
 *
 * ===========================================================================
 */
/** @brief opens if possible the instance of SPI requested */
CSL_SpiHandle CSL_spiOpen(
	/** pointer to the object that holds reference to the instance of SPI
	* requested after the call */
	CSL_SpiObj                            *hSpiObj,
	/** instance of SPI to which a handle is requested */
	CSL_InstNum                           spiNum,
	/** specifies if SPI should be opened with excusive or share access to
	* the associate pins */
	CSL_SpiParam                          *pSpiParam,
	/** This returns the status (success/errors) of the call */
	CSL_Status                            *status
);