Doxygen学习笔记1--基础

代码文档化

注释块：

#1 JAVADOC风格：

/**
内容
*/

#2 QT风格：

/*!
内容
*/

#3 替代方法：

///
/// 内容
///

//!
//! 内容
//!

确保最后留一行空行表示文档结尾

#4 其他方法

/*****************//**
内容
*********************/

/////////////////////
//内容
/////////////////////

简明描述：

#1 使用 \brief 命令，在一个段落后结束简明描述，紧跟一行空行，空行之后就是详细描述

/*! \brief 这里是简明描述
继续简明描述

这里是详细描述
*/

#2 需要设置 JAVADOC_AUTOBRIEF 为 YES，使用JAVADOC注释风格可直接触发一个简明描述，简明描述以一个点结尾，后跟一个空格或新起一行，之后就是详细描述

/** 简明描述. 详细描述

*/

/**简明描述.
详细描述
*/

此方式对C++注释风格同样有效

///简明描述.
///详细描述

#3 使用C++注释风格编写只有一行的简明描述，不能有多行简明描述

///简明描述.
/**详细描述*/

或者

///简明描述.

///详细描述
///继续详细描述

上面空行用于分割简明描述和详细描述，且 JAVADOC_AUTOBRIEF 要设置为 NO

如果想要实现多行的简明描述，可以按如下方式

//!简明
//!描述.
/*!详细描述
*/

如果想要讲某个成员变量、方法的描述内容放在其后方，则需要在注释块里添加<符号，这种方法也适用于函数参数描述。

int var;/*!<成员详细描述*/

int var;/**<成员详细描述
int var;//!<成员详细描述
        //!<

int var;///<成员详细描述
        ///<

如果设置成员的简明描述，使用如下方法

int var;//!<成员简明描述*/

int var;///<成员简明描述*/

在其他位置放置文档：

如果文档不能放在成员的前方，则需要对文件内容进行文档化。

要进行文档化，必须要使用结构化命令，因而在文本的前后端不能放置文档块，因为此时的文档块可能包含一些副本信息

扫描二维码关注公众号，回复： 3452036 查看本文章

特殊命令字请查阅 http://www.stack.nl/~dimitri/doxygen/manual/commands.html

要对一个文件进行文档化，首先要必须文档化文件，使用如下命令进行文件的文档化：

/*! \file */

或

/** @file */

*.h文档化的例子：

/*! \file structcmd.h
    \brief A Documented file.
    
    Details.
*/
/*! \def MAX(a,b)
    \brief A macro that returns the maximum of \a a and \a b.
   
    Details.
*/
/*! \var typedef unsigned int UINT32
    \brief A type definition for a .
    
    Details.
*/
/*! \var int errno
    \brief Contains the last error code.
    \warning Not thread safe!
*/
/*! \fn int open(const char *pathname,int flags)
    \brief Opens a file descriptor.
    \param pathname The name of the descriptor.
    \param flags Opening flags.
*/
/*! \fn int close(int fd)
    \brief Closes the file descriptor \a fd.
    \param fd The descriptor to close.
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
    \brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
    \param fd The descriptor to write to.
    \param buf The data buffer to write.
    \param count The number of bytes to write.
*/
/*! \fn int read(int fd,char *buf,size_t count)
    \brief Read bytes from a file descriptor.
    \param fd The descriptor to read from.
    \param buf The buffer to read into.
    \param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);

每一个注释块都包含结构化命令，为了改变存储位置在注释块中嵌入了成员的原型，导致当成员改变时，需要同时改变注释的内容

反正能写在成员之前就不要加上结构化命令写在另外的位置

列表：

使用列对齐的‘-’号可以实现列表的作用，‘+’号和‘*’号可以代替之，‘-’紧跟‘#’号可以生成带编号的列表，也可以用数字代替‘#’号

  /*! 
   *  A list of events:
   *    - mouse events
   *         -# mouse move event
   *         -# mouse click event\n
   *            More info about the click event.
   *         -# mouse double click event
   *    - keyboard events
   *         1. key down event
   *         2. key up event
   *
   *  More text here.
   */

如果列表使用TAB进行制表，则需要在TAB_SIZE选项中设置正确的TAB尺寸。

组合：

三种组合机制包括：“模块” “成员组” “子页面”

模块：

定义一个组需要在注释块中防止\defgroup命令，第一个参数是组的UID，第二个参数是组的名称或标题，使用此命令容易导致重定义错误，所以一般推荐使用\addtogroup命令，对于\addtogroup命令，标题是可选的。

在组的注释块中加入\ingroup可以在组中建立一个成员，

例子

/** @defgroup group1 The First Group
 *  This is the first group
 *  @{
 */
/** @brief class C1 in group 1 */
class C1 {};
/** @brief class C2 in group 1 */
class C2 {};
/** function in group 1 */
void func() {}
/** @} */ // end of group1
/**
 *  @defgroup group2 The Second Group
 *  This is the second group
 */
/** @defgroup group3 The Third Group
 *  This is the third group
 */
/** @defgroup group4 The Fourth Group
 *  @ingroup group3
 *  Group 4 is a subgroup of group 3
 */
/**
 *  @ingroup group2
 *  @brief class C3 in group 2
 */
class C3 {};
/** @ingroup group2
 *  @brief class C4 in group 2
 */
class C4 {};
/** @ingroup group3
 *  @brief class C5 in @link group3 the third group@endlink.
 */
class C5 {};
/** @ingroup group1 group2 group3 group4
 *  namespace N1 is in four groups
 *  @sa @link group1 The first group@endlink, group2, group3, group4 
 *
 *  Also see @ref mypage2
 */
namespace N1 {};
/** @file
 *  @ingroup group3
 *  @brief this file in group 3
 */
/** @defgroup group5 The Fifth Group
 *  This is the fifth group
 *  @{
 */
/** @page mypage1 This is a section in group 5
 *  Text of the first section
 */
/** @page mypage2 This is another section in group 5
 *  Text of the second section
 */
/** @} */ // end of group5
/** @addtogroup group1
 *  
 *  More documentation for the first group.
 *  @{
 */
/** another function in group 1 */
void func2() {}
/** yet another function in group 1 */
void func3() {}
/** @} */ // end of group1

生成结果看这里 http://www.stack.nl/~dimitri/doxygen/manual/examples/group/html/modules.html
出现的新命令：

@sa：指定类、方法、变量、文件、URL一个或多个的交叉引用，开始一个段落，使用“：：”或“#”，作为类和它的一个成员的引用连接符，来组合上述两个名称。在方法名称之后包含一个带括号的参数类型列表，用于若干重载方法或构造器的选择。

@link：生成一个链接，必须要以@endlink作为结束位置，@link和@endlink之间的内容作为链接的名字，@link命令之后的第一个参数为链接所指向的内容。

@ref：创建一个已命名章节、子章节、页面、锚链接的引用，对于输出HTML格式，将会产生一个指向这个章节的链接，对于一个章节或子章节会将链接的标题作为链接文本，对于一个锚链接可使用引号间的 text或者当 text 忽略时使用<name>作为链接文本。

@page：见后面子页面的介绍

组定义的优先级（从高到低）：\ingroup,\defgroup,\addtogroup,\weakgroup

成员组：

成员组定义方法：

//@{
.....
//@}

或者

/*@{*/
........
/*@}*/

在成员组标记之前可以放置一个单独的注释块，此块包含@name命令，用于指定组的头部也可以让注释块包含更多关于组的详细描述。

例子：

/** A class. Details */
class Memgrp_Test
{
  public:
    //@{
    /** Same documentation for both members. Details */
    void func1InGroup1();
    void func2InGroup1();
    //@}
    /** Function without group. Details. */
    void ungroupedFunction();
    void func1InGroup2();
  protected:
    void func2InGroup2();
};
void Memgrp_Test::func1InGroup1() {}
void Memgrp_Test::func2InGroup1() {}
/** @name Group2
 *  Description of group 2. 
 */
///@{
/** Function 2 in group 2. Details. */
void Memgrp_Test::func2InGroup2() {}
/** Function 1 in group 2. Details. */
void Memgrp_Test::func1InGroup2() {}
///@}
/*! \file 
 *  docs for this file
 */
//!@{
//! one description for all members of this group 
//! (because DISTRIBUTE_GROUP_DOC is YES in the config file)
#define A 1
#define B 2
void glob_func();
//!@}

生成结果看这里： http://www.stack.nl/~dimitri/doxygen/manual/examples/memgrp/html/index.html

出现的新命令：

@file：后可以跟源文件和头文件名称，用于对指定的文件进行说明，如果没有指定文件，则默认当前文件为指定文件进行说明。

如果设置 DISTRIBUTE_GROUP_DOC 为 YES ，则对成员组的描述将应用于所有成员。

子页面：

使用@page或者@mainpage命令可以合并到页面中，

预处理：

默认情况下支持局部预处理，它会判定编译语句和宏定义，但不会展开，如果要关闭预编译语句的判定，则可以设置 ENABLE_PREPROCESSING 为 NO。

如果想要展开所有预编译语句，则设置 MACRO_EXPANSION 为 YES

但如果宏定义嵌套太多，将会变得非常混乱，可以设置 EXPAND_ONLY_PREDEF 为YES，并在 PREDEFINED 或 EXPAND_AS_DEFINED 之后指定须展开的宏定义。

详细使用方法请参考官方手册 Preprocessing 一节。