doxygen可以为c++,c,java,IDL,php和c#等生成文档,生成的格式可以是html,latex,rtf,pdf,man等多种格式,甚至可以从无文档的源码中提取代码结构。
doxygen使用配置文件来决定所有设置,每个工程都应该有自己的配置文件,用doxygen -g <config-file>可以创建一个模板配置文件。配置文件的格式很像Makefile的文件格式。
如果要对已有的工程(使用doxygen未知的注释),可以使用EXTRACT_ALL选项。
使用命令doxygen <config-file>会在输入目录下生成一个html,rtf,latex,man目录,分别对应生成的四种格式的文档。
doxygen缺省为documented members,files,classes,namespace生成文档(EXTRACT_ALL为NO时)。
为使用doxygen在文档中进行注释
可以直接在注释中写带有客外标记的c/c++注释(特殊注释),这样doxygen就知道需要将其加入到文档中,有两种注释,一种是brief-简短单行的,一种是detail-详尽的。
几种方式的detail注释:
1.JavaDoc风格:
/**
* ...
*/
2.Qt风格:
/*!
* ...
*/
这两种中间的*都是可选的。
3.至少使用两个c++注释行,每行多加一个/或!:
///
/// ...
///
或
//!
//! ...
//!
4.有些人喜欢将注释变得醒目:
///////////////////////////
/// ...
///////////////////////////
几种brief注释:
1.在上述注释中使用brief,然后在一个空行后跟detail注释:
/*! brief Brief description.
* Brief Description continued.
*
* Detailed description starts here.
*/
2.如果配置文件中JAVADOC_AUTOBRIEF设为YES,则使用JavaDoc风格自动开始一个brief注释,这个注释以.跟一个空格或新行结束:
/** Brief description which ends at this dot. Details follow
* here.
*/
这也可以用到多行c++注释中:
/// Brief description which ends at this dot. Details follow
/// here.
3.可以用一种特殊的c++风格注释,每次不超过一行
/// Brief description.
/** Detailed description. */
或
//! Brief descripion.
//! Detailed description
//! starts here.
后一种的空行用来分开brief和detail注释。
doxygen只允许一个brief和一个detail描述。
如果一个brief在declaration前,一个在code前,那将使用declaration前的那个,detail也是,definition前的比declaration前的有更高优先级。
doxygen可以使用graphviz中的dot工具来生成c++类层次图。