用Doxygen生成文档

我是生成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