生成Doxygen文档

1.在源文件中添加Doxygen格式的源码注释

1.1分步指南

1. 文件注释
   

   放于文件的开头，例如：

   /**
   * @file       filename
   * @brief      This is a brief description.
   * @details This is the detail description.
   * @author     author
   * @date       date
   * @version A001
   * @par Copyright (c):
   *      XXX公司
   * @par History:       
   *   version: author, date, desc\n
   */

    

2. 函数注释

   放于函数声明前，例如：

   /** 下面是一个含有两个参数的函数的注释说明（简述）
    *
    *     这里写该函数的详述信息
    *    @param [in] a 被测试的变量         【参数描述1】
    *    @param [in] s 指向描述测试信息的字符串    【参数描述2】
    *    @return    测试结果 （return描述返回值）
    *    @see    Test()    （本函数参考其它的相关的函数，这里作一个链接）
    *    @note    (note描述需要注意的问题)
    */
   int testMe(int a,const char *s);

    

3. 数据结构注释

   应放于函数声明前，例如：

   /**
    * The brief description.
    * The detail description.
    */
   typedef struct
   {
       int var1;///<Description of the member variable
   }XXXX;
   或者
   typedef struct box {
       成员变量注释（enum的各个值也如此注释）：
       double length; ///< The length of the box
       double width; ///< The width of the box
       double height; ///< The height of the box
   };

    

4. 宏定义注释

   放于宏定义上方或者右侧，例如：

   /** Description of the macro */
   #define XXXX_XXX_XX      ox7fffffff
   或者
   #define XXXX_XXX_XX      0 ///< Description of the macro. 

    

5. 全局和静态变量注释

   /**  Description of global variable  */
   int g_xxx = 0;
   static int s_xxx = 0; ///<  Description of static variable

    

 

2.使用Doxygen工具，为添加了Doxygen格式注释的源码自动生成接口说明文档

2.1分步指南

1. 参照Doxygen源码注释规范，为源码添加注释
2. 安装Doxygen，如希望生成pdf格式说明，还需要安装支持latex格式解析的工具软件如MikTex
3. 运行Doxygen安装目录下的doxywizard，配置参数（输出latex，如果希望生成pdf版本）
   Mode → All Entities
   Output → HTML/Latex(for pdf)
4. 如需输出版本号，运行Doxygen，在Project的Project version or id处输入版本号即可

5. 在Run页面，选择Run doxygen，生成Doxygen配置文件及相应输出
   如果要生成pdf版本：对于中文注释或文档，需要先修改生成的latex\refman.tex

   写道

   1. 将
   \begin{document}
   替换为
   \usepackage{CJKutf8}
   \begin{document}
   \begin{CJK}{UTF8}{gbsn}
   
   2. 将
   \end{document}
   替换为
   \end{CJK}
   \end{document}
   
   3. 删除无用章节
   \chapter{使用说明}
   \label{md__r_e_a_d_m_e}
   \Hypertarget{md__r_e_a_d_m_e}
   \input{md__r_e_a_d_m_e}

    

6. 如需添加日期、文档制作者信息，则修改以下内容

   写道

   1.文档页脚的制作者信息：修改"制作者"后的信息
   \fancyfoot[RE]{\fancyplain{}{\bfseries\scriptsize 制作者 XXX }}
   \fancyfoot[LO]{\fancyplain{}{\bfseries\scriptsize 制作者 XXX }}
   
   2.添加信息：
   Large后为输入项，可自行输入显示的文本
   [lex]为换行标识，会自动换行显示
   \begin{center}%
   {\Large xxx接口文档 \\[1ex]\large version XXX }\\
   \vspace*{1cm}
   {\large 2017.7.20}\\

    

7. 在生成的latex目录下运行make，编译生成pdf说明文件