使用 Doxygen 来生成文档需要遵从的注释语法
开源工程
可以搜索参考用法
注释
- 注释块
/** * comment text here */ int x = 0; - 行尾注释
int x = 0; ///< comment text here - 单行注释
/// comment text here int x = 0;
标记
注释块中可以使用一些特殊的标记，比如 brief 标记，官方称为 Special Commands
例如
\struct <name> [<header-file>] [<header-name>]\typedef (typedef declaration)\brief { brief description }
标记可以有两种书写方式 \param 或者 @param，每个命令有一个或多个参数，每个参数都有明确的范围：
<>参数是一个单独单词()参数一直到命令所在的结束[]参数是可选的{}参数一直延伸到本段结束。一个段落的结束以一个空行来标识，或者是一个段落标记
常用标记
\brief { brief description }可以省略\param '['dir']' <parameter-name> { parameter description }/** * @param[out] dest The memory area to copy to. * @param[in] src The memory area to copy from. * @param[in] n The number of bytes to copy */ void memcpy(void *dest, const void *src, size_t n);\return { description of the return value }返回说明\retval <return value> { description }返回值\ref <name> ["(text)"]引用/** * @return 程序执行成功与否 * @retval 0 程序执行成功 * @retval 1 程序执行失败 * @note 这里只是一个简单的例子 */ int main(int argc, char* argv[])\note { text }标注需要特别注意的地方\deprecated { description }\warning { warning message }接口容易出错的地方\sa { references }\see { references }
Example
Example FFMPEG
**
* Initialize the AVCodecContext to use the given AVCodec. Prior to using this
* function the context has to be allocated with avcodec_alloc_context3().
*
* The functions avcodec_find_decoder_by_name(), avcodec_find_encoder_by_name(),
* avcodec_find_decoder() and avcodec_find_encoder() provide an easy way for
* retrieving a codec.
*
* @warning This function is not thread safe!
*
* @note Always call this function before using decoding routines (such as
* @ref avcodec_receive_frame()).
*
* @code
* avcodec_register_all();
* av_dict_set(&opts, "b", "2.5M", 0);
* codec = avcodec_find_decoder(AV_CODEC_ID_H264);
* if (!codec)
* exit(1);
*
* context = avcodec_alloc_context3(codec);
*
* if (avcodec_open2(context, codec, opts) < 0)
* exit(1);
* @endcode
*
* @param avctx The context to initialize.
* @param codec The codec to open this context for. If a non-NULL codec has been
* previously passed to avcodec_alloc_context3() or
* for this context, then this parameter MUST be either NULL or
* equal to the previously passed codec.
* @param options A dictionary filled with AVCodecContext and codec-private options.
* On return this object will be filled with options that were not found.
*
* @return zero on success, a negative value on error
* @see avcodec_alloc_context3(), avcodec_find_decoder(), avcodec_find_encoder(),
* av_dict_set(), av_opt_find().
*/注释 struct
/**
* @struct AC3HeaderInfo
* Coded AC-3 header values up to the lfeon element, plus derived values.
*/
typedef struct AC3HeaderInfo {
/** @name Coded elements
* @{
*/
uint16_t sync_word;
uint16_t crc1;
uint8_t sr_code;
uint8_t bitstream_id;
uint8_t bitstream_mode;
uint8_t channel_mode;
uint8_t lfe_on;
uint8_t frame_type;
int substreamid; ///< substream identification
int center_mix_level; ///< Center mix level index
int surround_mix_level; ///< Surround mix level index
uint16_t channel_map;
int num_blocks; ///< number of audio blocks
int dolby_surround_mode;
/** @} */
/** @name Derived values
* @{
*/
uint8_t sr_shift;
uint16_t sample_rate;
uint32_t bit_rate;
uint8_t channels;
uint16_t frame_size;
uint64_t channel_layout;
/** @} */
} AC3HeaderInfo;
/**
* @brief Example class的简易说明
*
* 本范例说明Example class。
* 这是一个极为简单的范例。
*
*/
class Example {
private:
int var1 ; ///< 这是一个private的变数
public:
int var2 ; ///< 这是一个public的变数成员。
int var3 ; ///< 这是另一个public的变数成员。
void ExFunc1(void);
int ExFunc2(int a, char b);
char *ExFunc3(char *c) ;
};