生成Doxygen文档
程序员文章站
2022-06-01 14:26:02
...
1.在源文件中添加Doxygen格式的源码注释
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 */
-
函数注释
放于函数声明前,例如:
/** 下面是一个含有两个参数的函数的注释说明(简述) * * 这里写该函数的详述信息 * @param [in] a 被测试的变量 【参数描述1】 * @param [in] s 指向描述测试信息的字符串 【参数描述2】 * @return 测试结果 (return描述返回值) * @see Test() (本函数参考其它的相关的函数,这里作一个链接) * @note (note描述需要注意的问题) */ int testMe(int a,const char *s);
-
数据结构注释
应放于函数声明前,例如:
/** * 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 };
-
宏定义注释
放于宏定义上方或者右侧,例如:
/** Description of the macro */ #define XXXX_XXX_XX ox7fffffff 或者 #define XXXX_XXX_XX 0 ///< Description of the macro.
-
全局和静态变量注释
/** Description of global variable */ int g_xxx = 0; static int s_xxx = 0; ///< Description of static variable
2.使用Doxygen工具,为添加了Doxygen格式注释的源码自动生成接口说明文档
2.1分步指南
- 参照Doxygen源码注释规范,为源码添加注释
- 安装Doxygen,如希望生成pdf格式说明,还需要安装支持latex格式解析的工具软件如MikTex
- 运行Doxygen安装目录下的doxywizard,配置参数(输出latex,如果希望生成pdf版本)
Mode → All Entities
Output → HTML/Latex(for pdf) - 如需输出版本号,运行Doxygen,在Project的Project version or id处输入版本号即可
-
在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} -
如需添加日期、文档制作者信息,则修改以下内容
写道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}\\ -
在生成的latex目录下运行make,编译生成pdf说明文件
上一篇: 敏捷开发中QA的职责之敏捷中的QA
下一篇: [Linux] Ubuntu安装资料