DOXYGEN简明实用教程

本文档主要适用于UbuntuKylin15.04.

Doxygen（http://www.doxygen.nl/download.html）能够自动根据代码建立文档，是一个很是好的工具，能够支持不少种语言，快速生成类、文件、注释等一体的文档，可以输出html/latex等多种文档格式。

1、安装

获取最新版本，可使用下面的脚本进行安装。

#须要BISON和FLEX支持。
sudo apt-get install FLEX BISON
git clone https://github.com/doxygen/doxygen.git
cd doxygen
make
sudo make install

或者直接安装：

#这个是生成类图的工具，须要预先安装。
sudo apt-get install graphviz
sudo apt-get install doxygen

2、使用流程

先建立一个控制文档的模版文件：

doxygen -g doc.dot

进去修改输入、输出路径、各类参数。里面有详细的注释，一看就明白。

gedit doc.dot

生成最终的文档，将输出到文档中制定的OUTPUT_PATH目录位置。

doxygen doc.dot

3、使用经验和参数说明

一些经验，谨供参考：

 -----------------------------------------------------------------------------------

1.全部注释均可以使用///开始(C++风格)。
2.类体前必须加上///描述，不然会产生警告【Compound 类名 is not documented】
  描述中最好不要带有此类的类名，不然会产生两个连接(但指向同一个文件)影响美观。
3.public和protected会自动生成，可是private要在Expert的Build选项里勾中EXTRACT_PRIVATE，static成员也是如此。
4.函数注释方式
 

   /// Constructor【函数描述】
    /// @param [in] pos       The position of Camera in world coordinate         【参数描述1】
    /// @param  [in] lookat    The point Camera looks at in world coordinate    【参数描述2】
   /// BaseCamera( const D3DXVECTOR3& pos, const D3DXVECTOR3& lookat );

5.变量注释方式
    D3DXVECTOR3 m_Position;    /*!< Camera position point in world coordinate */   或
    D3DXVECTOR3 m_Position;    ///< Camera position point in world coordinate
两种方式产生的结果不一样。前者会单独产生一块Member Data Documentation注释，后者会在Pubilc/Protected/Private Attributes变量描述后紧跟注释。
6.@参数和\参数相同
7.产生描述顺序和注释顺序相同，通常风格为：
 

   /// 函数描述
    /// 
@param
      参数描述
    /// 
@return
      返回值描述
    /// @retval     返回值1     返回值1描述
    /// @retval     返回值2     返回值2描述
    /// @remarks     注意事项
    /// @note    注意事项，功能同@remarks,显示字样不一样
    /// @par    自定义图块，后面可跟示例代码之类
    /// @code(必须使用@endcode结束)
    /// 示例代码(无需缩进)    
    /// @endcode
    /// @see     其余参考项【产生指向参考的连接】
    ///函数代码声明

8.特殊符号
    /// -        产生一个黑色圆点
9.定义在类体里面的enum
  

 /// Camera types
    enum CAMERA_TYPE
    {
        CAMERA_FIRST_VIEW,/*!< Camera that looks from the first view */
        CAMERA_MODEL_VIEW,///< Camera that looks from the third view
    };

    两种风格相同。如下开始的项都是全局非类内定义，在文件最开始(我尝试是在include以前) 必须加上【/// \file 文件名】，不然不会生成注释【没有File Member页】。10. 定义在文件里面的宏     #define CAMERA_TYPE_NUMBER     ///< The number of camera types.       或     #define CAMERA_TYPE_NUMBER     /*!< The number of camera types. */    风格说明见5。11. 非类内enum定义同10.        两种风格相同。见9。12. 非类内typedef定义同10.     风格说明见5。