用Doxygen生成文档

最新推荐文章于 2022-08-21 11:18:50 发布

weixin_34376986

最新推荐文章于 2022-08-21 11:18:50 发布

阅读量61

点赞数

原文链接：http://www.cnblogs.com/foohack/p/4663350.html

版权

我是生成C/C++的文档，输出html格式的文档。就不做成CHM了。

注释要这种写：（当然，有数种注释风格，选择任意你喜欢的就行）

1 /**
2 *
3 *    一系列的doxygen的 command
4 *
5 *
6 */

具体参考这里：http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html

我常用的就@class @brief @enum @fn @return @throws @param[in] @param[out] @date @file @warning

所有指令的参考：http://www.stack.nl/~dimitri/doxygen/manual/commands.html#cmd_intro

如果要支持以上注释风格的文档化，必须在DoxyFile（配置文件）中的变量 JAVADOC_AUTOBRIEF 设置为YES。

下面是源文件注释的样例参考：’

  1 /**
  2 *  @file novella.h
  3 *  @brief 控制Novella变频器
  4 *  @author Alex Chen
  5 *  @version 1.0  
  6 * @date 2015-7-19
  7 */
  8 
  9   
 10 #ifndef NOVELLA_H
 11 #define NOVELLA_H
 12 
 13 #include <string>
 14 #include "snmp_pp/snmp_pp.h"
 15 
 16 #define  NOVELLA_EXPORT
 17 
 18 #ifdef NOVELLA_EXPORT
 19 #define   NOVELLA_API __declspec(dllexport)
 20 #else
 21 #define NOVELLA_API //__declspec(dllimport)
 22 #endif
 23 
 24 class CSerialPort;
 25 
 26 typedef int BOOL;
 27 #define bTRUE 1
 28 #define bFALSE 0
 29 
 30 template   class  __declspec (dllexport) std::basic_string<char>;
 31 
 32 /**
 33 *  @class Novella
 34 *  @brief 访问控制变频器的类
 35 */
 36 class NOVELLA_API Novella{
 37 
 38 public:
 39     /**
 40     *    @enum PROTOCOL
 41     *    @brief 与设备通信的协议类型
 42     */
 43     enum PROTOCOL
 44     {
 45         SERIAL_PORT,  /**< 串口 */
 46         SNMP,         /**< SNMP协议 */
 47         NETWORK       /**< 网络协议，目前无效保留参数*/
 48     };
 49 
 50   
 51     /**
 52     *    用于初始化串口的构造函数。并打开设备。
 53     *    @fn Novella(const std::string &comName, char dev_addr, const PROTOCOL& protocol, int baud = 9600, char parity = 'N', int databits = 8, int stopbits = 1)
 54     *    @param[in] comName 串口名，大小写不敏感。
 55     *    @param[in] dev_addr 变频器的设备地址，地址的形式是字符A,B,C,D,E ,依此类推。目前只支持到E。
 56     *    @param[in] protocol 使用何种协议对设备进行访问
 57     *   @param[in] baud 波特率
 58     *   @param[in] parity 校验位
 59     *   @param[in] databits 数据位
 60     *   @param[in] stopbits 停止位
 61     *    @throws -1 打开串口失败
 62     */
 63     Novella(const std::string &comName, char dev_addr, const PROTOCOL& protocol, int baud = 9600, char parity = 'N', int databits = 8, int stopbits = 1);
 64     
 65     /**
 66     *    用于初始化SNMP协议的构造函数。并打开设备
 67     *    @fn Novella(const std::string &ip,const std::string &dev_type, const PROTOCOL& protocol)
 68     *    @param[in] ip 设备的IP地址。
 69     *    @param[in] protocol 使用何种协议对设备进行访问。
 70     */
 71     Novella(const std::string &ip, const PROTOCOL& protocol);
 72     
 73     /**
 74     *    析构函数，关闭设备。
 75     *    @fn ~Novella()
 76     */
 77     ~Novella();
 78     
 79     /**
 80     *    得到设备类型，目前为无效保留函数
 81     *    @fn std::string getDevType() const
 82     *    @return 返回值为设备类型
 83     */
 84     std::string getDevType() const;
 85     
 86     /**
 87     *    获取设备中心频点
 88     *    @fn int getFreq(int& freq)
 89     *    @param[out]  freq 频率值
 90     *    @return 返回值为-1表示失败，为0表示成功
 91     */
 92     int getFreq(int& freq);
 93     
 94     /**
 95     *    设置设备中心频点
 96     *    @fn int    setFreq(int freq)
 97     *    @param[in]  freq 频率值
 98     *    @return 返回值为-1表示失败，为0表示成功
 99     */
100     int    setFreq(int freq);
101 
102     /**
103     *    获取设备是否为远程模式
104     *    @fn int getRemote(bool& remote)
105     *    @param[out]  remote true为远程模式，false为本地模式
106     *    @return 返回值为-1表示失败，为0表示成功
107     */
108     int getRemote(bool& remote);
109     
110     /**
111     *    设置设备是否为远程模式
112     *    @fn int setRemote(bool remote)
113     *    @param[in]  remote true为远程模式，false为本地模式
114     *    @return 返回值为-1表示失败，为0表示成功
115     */
116     int setRemote(bool remote);
117     
118     /**
119     *    获取设备的衰减值
120     *    @fn int getAtten(int &atten)
121     *    @param[out]  atten 衰减值
122     *    @return 返回值为-1表示失败，为0表示成功
123     */
124     int getAtten(int &atten);
125     
126     /**
127     *    设置设备的衰减值
128     *    @fn int setAtten(int atten)
129     *    @param[in]  atten 衰减值
130     *    @return 返回值为-1表示失败，为0表示成功
131     */
132     int setAtten(int atten);
133 
134     /**
135     *    获取设备是否为静音模式
136     *    @fn int getMute(bool &mute)
137     *    @param[out]  mute  true为静音模式，false为非静音模式
138     *    @return 返回值为-1表示失败，为0表示成功
139     */
140     int getMute(bool &mute);
141     
142     /**
143     *    设置设备是否为静音模式
144     *    @fn int setMute(bool mute)
145     *    @param[in]  mute  true为静音模式，false为非静音模式
146     *    @return 返回值为-1表示失败，为0表示成功
147     */
148     int setMute(bool mute);
149 
150     /**
151     *    获取设备的Spectrum状态
152     *    @fn int getInvert(bool &invert)
153     *    @param[out]    true为Invert，false为为Preserve
154     *    @return 返回值为-1表示失败，为0表示成功
155     */
156     int getInvert(bool &invert);
157     
158     /**
159     *    获取设备的Spectrum状态
160     *    @fn int setInvert(bool invert)
161     *    @param[in]    true为Invert，false为Preserve
162     *    @return 返回值为-1表示失败，为0表示成功
163     */
164     int setInvert(bool invert);
165 
166     
167 
168 private:
169 
170     SerialPort/
171     //status request
172     void StatusRequestCommand(char addr);
173 
174     int FreqGet(int &freq);
175     int AttenGet(int &adde);
176     int MuteGet(BOOL &mute);
177     int RemoteGet(BOOL &remote);
178     int InvertGet(BOOL &invert);
179 
180 
181     bool SerialSend(char *ch);
182     bool SerialRead(char *data);
183 
184     int Command_5bit(char conaddr, char com);
185 
186     ////snmp///
187 
188     std::string get_param(const char *param, std::string value);
189     int get_param(const char *param, int &value);
190     void set_param_int(const char *param, int value);
191 
192 
193 private:
194 
195     
196     ////SerialPort//
197     
198     CSerialPort *m_serialPort;
199 
200 
201     char m_dev_addr;
202     int m_freq;
203     int m_atten;
204     
205     bool m_isRemote;
206     bool m_isInvert;
207     bool m_isMute;
208     bool m_bSerialPortOpened;
209     
210     std::string m_devType;
211     std::string m_comName;
212     std::string m_ip;
213     
214     PROTOCOL m_currentProtocol;
215 
216 
217     ////snmp//
218 
219 
220     std::string m_unitname;
221     BOOL m_remote;
222     BOOL m_invert;
223     BOOL m_mute;
224 
225 
226     //----------snmp parameters----------------------
227     snmp_version version;
228     int retries;
229     int timeout;
230     u_short port;
231 
232     UdpAddress *nfcaddress;
233     Snmp *snmp;
234     CTarget *ctarget;
235 
236     
237 
238 };
239 
240 #endif

View Code

配置文件用DoxyGen自带的GUI前端工具生成个配置文件的框架（front-end工具说明在这里：http://www.stack.nl/~dimitri/doxygen/manual/doxywizard_usage.html），然后自己用文本编辑器改就行了。就不做介绍了。

这里有配置文件的变量开关的作用介绍：http://www.stack.nl/~dimitri/doxygen/manual/config.html

一般我就用到

PROJECT_NAME = 你的工程名

FILE_PATTERNS = 如果是C/C++的，就设置为

1 FILE_PATTERNS          = *.c \
2                          *.cc \
3                          *.cxx \
4                          *.cpp \
5                          *.c++ \
6                          *.h \
7                          *.hxx \
8                          *.hpp \

PROJECT_BRIEF = 你的工程简介

OUTPUT_DIRECTORY = 工程文档生成输出的目录路径

OUTPUT_LANGUAGE = 文档的语言，如果是中文就设成Chinese

JAVADOC_AUTOBRIEF = 一般设置为YES

DOXYFILE_ENCODING = DoxyFile文件本身的编码格式，用UTF-8不带BOM

INPUT = 源文件的路径，一般DoxyFile也放这个路径下

INPUT_ENCODING = 源文件的编码，一般用UTF-8不带BOM

RECURSIVE = 一般设置为YES，这样可以递归处理源文件子目录

EXCLUDE_PATTERNS = 用来设置忽略子目录的。就是不把某目录，或者文件，当作输入文件，不想文档化的东西可以包含进来

1 EXCLUDE_PATTERNS       = */snmp++/* \
2                          */Debug/*  \
3                          */ipch/*    \

比如以上是VS系列的东西，Debug，和ipch，SNMP++里面的东西我不想文档化。

INLINE_SOURCES = 文档内嵌代码接口实现，一般我设置为YES。如果公开给客户，需要关闭吧，设置为NO

STRIP_CODE_COMMENTS = 一般设置为YES，忽略非特殊格式的注释，就是普通注释

GENERATE_HTML = 设置为YES，如果需要要生成html格式的
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html html格式的文件后缀

一般以下几个变量我都会设置为YES，调用关系图和包含关系图等。

INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES

最后配置文件写完了就是使用doxygen命令：

doxygen [DoxyFile]

具体参考这里用法：http://www.stack.nl/~dimitri/doxygen/manual/doxygen_usage.html

可能用到的额外工具：

iconv------这个用来递归处理某路径下源文件的编码转换。这样在用Doxygen文档化源代码

references：

http://blog.csdn.net/fmddlmyy/article/details/1663898

转载于:https://www.cnblogs.com/foohack/p/4663350.html

weixin_34376986

关注

0
点赞
踩
0

收藏

觉得还不错? 一键收藏
0
评论
用Doxygen生成文档

我是生成C/C++的文档，输出html格式的文档。就不做成CHM了。注释要这种写：（当然，有数种注释风格，选择任意你喜欢的就行）1 /**2 *3 * 一系列的doxygen的 command4 *5 *6 */具体参考这里：http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html我常用的...
复制链接

扫一扫