用Doxygen生成文档

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

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

 /**
 *
 *    一系列的doxygen的 command
 *
 *
 */

具体参考这里：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。

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

 /**
 *  @file novella.h
 *  @brief 控制Novella变频器
 *  @author Alex Chen
 *  @version 1.0
 * @date 2015-7-19
 */

 #ifndef NOVELLA_H
 #define NOVELLA_H

 #include <string>
 #include "snmp_pp/snmp_pp.h"

 #define  NOVELLA_EXPORT

 #ifdef NOVELLA_EXPORT
 #define   NOVELLA_API __declspec(dllexport)
 #else
 #define NOVELLA_API //__declspec(dllimport)
 #endif

 class CSerialPort;

 typedef int BOOL;
 #define bTRUE 1
 #define bFALSE 0

 template   class  __declspec (dllexport) std::basic_string<char>;

 /**
 *  @class Novella
 *  @brief 访问控制变频器的类
 */
 class NOVELLA_API Novella{

 public:
     /**
     *    @enum PROTOCOL
     *    @brief 与设备通信的协议类型
     */
     enum PROTOCOL
     {
         SERIAL_PORT,  /**< 串口 */
         SNMP,         /**< SNMP协议 */
         NETWORK       /**< 网络协议，目前无效保留参数*/
     };

     /**
     *    用于初始化串口的构造函数。并打开设备。
     *    @fn Novella(const std::string &comName, char dev_addr, const PROTOCOL& protocol, int baud = 9600, char parity = 'N', int databits = 8, int stopbits = 1)
     *    @param[in] comName 串口名，大小写不敏感。
     *    @param[in] dev_addr 变频器的设备地址，地址的形式是字符A,B,C,D,E ,依此类推。目前只支持到E。
     *    @param[in] protocol 使用何种协议对设备进行访问
     *   @param[in] baud 波特率
     *   @param[in] parity 校验位
     *   @param[in] databits 数据位
     *   @param[in] stopbits 停止位
     *    @throws -1 打开串口失败
     */
     Novella(const std::string &comName, char dev_addr, const PROTOCOL& protocol, int baud = , char parity = 'N', int databits = , int stopbits = );

     /**
     *    用于初始化SNMP协议的构造函数。并打开设备
     *    @fn Novella(const std::string &ip,const std::string &dev_type, const PROTOCOL& protocol)
     *    @param[in] ip 设备的IP地址。
     *    @param[in] protocol 使用何种协议对设备进行访问。
     */
     Novella(const std::string &ip, const PROTOCOL& protocol);

     /**
     *    析构函数，关闭设备。
     *    @fn ~Novella()
     */
     ~Novella();

     /**
     *    得到设备类型，目前为无效保留函数
     *    @fn std::string getDevType() const
     *    @return 返回值为设备类型
     */
     std::string getDevType() const;

     /**
     *    获取设备中心频点
     *    @fn int getFreq(int& freq)
     *    @param[out]  freq 频率值
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int getFreq(int& freq);

     /**
     *    设置设备中心频点
     *    @fn int    setFreq(int freq)
     *    @param[in]  freq 频率值
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int    setFreq(int freq);

     /**
     *    获取设备是否为远程模式
     *    @fn int getRemote(bool& remote)
     *    @param[out]  remote true为远程模式，false为本地模式
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int getRemote(bool& remote);

     /**
     *    设置设备是否为远程模式
     *    @fn int setRemote(bool remote)
     *    @param[in]  remote true为远程模式，false为本地模式
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int setRemote(bool remote);

     /**
     *    获取设备的衰减值
     *    @fn int getAtten(int &atten)
     *    @param[out]  atten 衰减值
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int getAtten(int &atten);

     /**
     *    设置设备的衰减值
     *    @fn int setAtten(int atten)
     *    @param[in]  atten 衰减值
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int setAtten(int atten);

     /**
     *    获取设备是否为静音模式
     *    @fn int getMute(bool &mute)
     *    @param[out]  mute  true为静音模式，false为非静音模式
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int getMute(bool &mute);

     /**
     *    设置设备是否为静音模式
     *    @fn int setMute(bool mute)
     *    @param[in]  mute  true为静音模式，false为非静音模式
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int setMute(bool mute);

     /**
     *    获取设备的Spectrum状态
     *    @fn int getInvert(bool &invert)
     *    @param[out]    true为Invert，false为为Preserve
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int getInvert(bool &invert);

     /**
     *    获取设备的Spectrum状态
     *    @fn int setInvert(bool invert)
     *    @param[in]    true为Invert，false为Preserve
     *    @return 返回值为-1表示失败，为0表示成功
     */
     int setInvert(bool invert);

 private:

     ////////////////////////SerialPort/////////////////////
     //status request
     void StatusRequestCommand(char addr);

     int FreqGet(int &freq);
     int AttenGet(int &adde);
     int MuteGet(BOOL &mute);
     int RemoteGet(BOOL &remote);
     int InvertGet(BOOL &invert);

     bool SerialSend(char *ch);
     bool SerialRead(char *data);

     int Command_5bit(char conaddr, char com);

     ////////////////////////////////snmp///////////////

     std::string get_param(const char *param, std::string value);
     int get_param(const char *param, int &value);
     void set_param_int(const char *param, int value);

 private:

     ////////////////////////////SerialPort//////////////////////////

     CSerialPort *m_serialPort;

     char m_dev_addr;
     int m_freq;
     int m_atten;

     bool m_isRemote;
     bool m_isInvert;
     bool m_isMute;
     bool m_bSerialPortOpened;

     std::string m_devType;
     std::string m_comName;
     std::string m_ip;

     PROTOCOL m_currentProtocol;

     ////////////////////////////////snmp//////////////////////////

     std::string m_unitname;
     BOOL m_remote;
     BOOL m_invert;
     BOOL m_mute;

     //----------snmp parameters----------------------
     snmp_version version;
     int retries;
     int timeout;
     u_short port;

     UdpAddress *nfcaddress;
     Snmp *snmp;
     CTarget *ctarget;

 };

 #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++的，就设置为

 FILE_PATTERNS          = *.c \
                          *.cc \
                          *.cxx \
                          *.cpp \
                          *.c++ \
                          *.h \
                          *.hxx \
                          *.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 = 用来设置忽略子目录的。就是不把某目录，或者文件，当作输入文件，不想文档化的东西可以包含进来

 EXCLUDE_PATTERNS       = */snmp++/* \
                          */Debug/*  \
                          */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