用doxygen为程序生成文档

 

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++类层次图。