欢迎您访问程序员文章站本站旨在为大家提供分享程序员计算机编程知识!
您现在的位置是: 首页

生成Doxygen文档

程序员文章站 2022-06-01 14:26:02
...

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说明文件

相关标签: 文档