用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
配置文件用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
