doxygen相关问题
doxygen相关问题
我主要的设置有
现在 wizard对话框中大体设置下,然后
export设置:
project->DOXYFILE_ENCODING=GBK
project->OUTPUT_LANGUAGE=chinese
input->INPUT_ENCODING=GBK
Dot->HAVE_DOT
Dot-> UML_LOOK
Dot->CALL_GRAPH
Dot->CALLER_GRAPH
http://www.fmddlmyy.cn/text21.html
http://blog.csdn.net/fengrx/archive/2009/09/15/4554830.aspx
下载doxygen的binary 包
doxygen下载地址
http://www.10.xdowns.com/uploadFile/2007-7/doxygen.rar
为了使doxygen能够将类图、协作图等加入到文档中，还要下载安装graphviz for win。
graphviz 2.18下载：
http://www.graphviz.org/pub/graphviz/ARCHIVE/graphviz-2.18.exe
全部安装后就可以开始使用了。
运行doxygen wizard.exe
如 果你像我一样希望只通过图形界面运行doxygen的话，请在doxygen的bin目录中运行doxywizard.exe，这时按照doxygen根 目录下的文档（doxygen_manual-1.5.2.chm）中 Doxywizard usage一节的说明设置即可。主要包括，源码路径、工作路径、输出路径等。
点开始，即可生成文档
最后对文档生成过程中遇到的一些问题进行说明：
1 中文问题：中文注释在文档中是乱码。
解决：在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”，这样基于GB的文本编辑器生成的代码就可以正常使用了。
但是，还有一个无法彻底解决的问题就是，当输出语言为中文时左边的导航栏的所有中文仍然是乱码。哪位有解决方案，请务必告知！
2 图形问题：无法绘制类图协作图等图形。
首 先确保安装了graphviz for win，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。然后在 expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。
如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。
3 输出chm的问题：如何输出.chm文件
1. 你必须安装微软或其相兼容的chm编译系统。通常为HTML Help Workshop。
2. 首先在[Wizard...]的Output页面中，选择HTML，然后选择到prepare for compressed HTML(.chm)。
3. 其次在[Expert...]的HTML页面中，将HHC_LOCATION指向微软的hhc工具。通常为C:/Program Files/HTML Help Workshop/hhc.exe。然后点击OK，保存，编译即可。
HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。
HTML Help Workshop 地址：
4 如何像MSDN那样在左边的树中显示函数列表？
打开[Expert...]的HTML页面，然后选中TOC_EXPAND即可。
5 如何去掉CHM附带的CHI文件？
注 意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了CHM，而没有上传CHI文件，导致无法正常显示的 情况。我不知道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。打开[Expert...]的HTML页面，取消GENERATE_CHI 即可。
6 如何像MSDN那样右边每页显示一个函数？
这个问题其实比较棘手，在[Expert...]中的 Project页面，下面有一个选项叫做SEPARATE_MEMBER_PAGES，把这个选项选中，这样每个函数就是一个页。但是会有一个问题，那就 是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法去掉。我的解决方法就是自己编译一下doxygen，在 memberlist.cpp的writeDocumentationPage函数中将 container->writeQuickMemberLinks(ol,md);连同附近几行屏蔽掉即可。
7 如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？
这 个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。这个功能需要修改源代码。在index.cpp中，屏蔽 writeGroupIndexItem函数的 Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和 Doxygen::indexList.decContentsDepth();即可，具体不解释了，一看便知。
8 如何修改或者去掉右下脚Generated at ...的文字？
打 开[Expert...]的HTML页面，然后在HTML_FOOTER中指定相应的HTML文件即可。注意HTML_FOOTER中至少包含BODY和 HTML结束标记。即一个最小的尾部HTML至少是这样</BODY></HTML>。同理，如果你要指定了 HTML_HEADER，他至少包含<HTML><HEAD></HEAD><BODY>
9 如何生成组？
组 就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是 通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数就 被放置在同一个组中。
10 如何生成中文帮助？
点击[Expert...]，在页Project 的OUTPUT_LANGUAGE，选择Chinese，这样输出的帮助提示信息就是中文。具体中文提示信息的文字在源代码中。
11 如何彻底解决DoxyGen的输出中文chm的乱码问题？
DoxyGen的实现中大概有三处编码的设置。首先是，doxyfile，也就是配置文件。其次，INPUT_ENCODING，也就是DoxyGen需要解析的输入文件的编码。最后，就是输出的编码。譬如CHM左边的索引编码。
首 先是chm的标题乱码，这个比较好解决，因为DoxyWizard使用QT做的界面，它内部做了转换，所以在DoxyWizard中输入中文，在保存的时 候，他自己做了转码，导致doxyfile中的最终的保存信息不正确。这个时候只需要用记事本打开doxyfile配置文件，输入相应中文即可。注意保存 的时候保存成ANSI编码即可。保存成其他格式的话可能需要去掉BOM，比较麻烦，没研究了。这个相应的编码设置在[Expert...]中，页 Project 的 DOXYFILE_ENCODING，不输入或者默认为UTF-8都行。
其次是右边内容乱码，这个多半是因为你没 有配置好输入的文件编码类型造成的。在[Expert...]的Input页面中，有一个INPUT_ENCODING，这个选项表示输入文件的编码方 式，这要和你处理的源文件格式一致。对于我们来说（使用vs的人），一般设置为GB2312。当然，再次声明，编码方式取决于源文件的编码方式。如果文件 编码已经是UTF-8了，然而你还将其设置成GB2312，那么DoxyGen会将UTF-8当成ANSI再进行一次UTF-8转换，自然会出错了。
最 后也是经常遇到的问题就是DoxyGen生成的CHM文件的左边树目录的中文变成了乱码。这个只需要将chm索引的编码类型修改为GB2312即可。在 HTML的CHM_INDEX_ENCODING中输入GB2312即可。然而这种方法下，还有一个瑕疵之处，就是chm的搜索页的搜索结果中显示的中文 文字却变成乱码了。这是因为DoxyGen默认开启了HTML Help Workshop的Full-text search全文搜索选项，他在进行全文搜索的时候，应该是打开文件然后按照ANSI进行搜索的，（资料表示HHW不支持UTF-8，仅支持ISO- 8859-1或者windows-1252编码。）而Doxygen生成的右边界面统一是UTF-8，这自然出现了问题。而在这种情况下做全文搜索，理论 上只能搜索英文。
无奈，我们的解决方案只能是重新编译DoxyGen代码，为了满足搜索，只要保证右边的页面文件不是UTF-8即可。 我们首先修改writeDefaultHeaderFile这个函数的代码，将其charset=GB2312。然后在 TranslatorDecoder的构造函数中修改m_toUtf8 = (void*)-1;即屏蔽文本写入时最终的转换函数。最后删除INPUT_ENCODING的设置或者输入UTF-8。这样会使DoxyGen认为我们 的文本是UTF-8的，从而不用进行转换。生成替换原始的DoxyGen即可。
另外需要补充的是，还有一种方案是不用修改作者的源代码，但是需要将DoxyGen生成的右边的HTML文件使用工具（如iconv）手工转换成GB2312，然后再使用HTML Help Workshop生成，网上有篇文章介绍过，我测试一下，也是没有问题的。
最后，doxygen是一个开源项目，并且支持vs2005项目，这样一来，如果你觉得哪里不顺手，完全可以把代码下载后自行编译。虽然我感觉doxygen的代码写的不能算是perfect，但是对于一个这样的工程，我们无论如何都需要一种敬意。祝好运~
这样，基本上就能够用doxygen生成漂亮的文档了。代码方面，doxygen支持多种格式的注释风格，根据manual选择自己喜欢的就好。
相关参考：
DOXYGEN简明实用教程
代码写多了难免需要做文档，给自己还是给别人看都需要如此，这次XBOX360制作，前期没怎么写注释，回头改Bug都要猜半天自己写的代码是什么意思。更别提别人写的东西，100行代码也没有一句注释，幸好不是我维护，否则要疯掉了。
花了一天功夫尝试了一下Doxygen的使用，还好不难，但是有些磕磕绊绊，它自己的文档也说不清楚，网上搜出来的教程也只是给出样子，遇到的问题还是靠自己尝试了几十次才搞定。
不管如何，常用的东西都可以弄出来了。贴在下面：
-----------------------------------------------------------------------------------
1.所有注释都可以使用///开始(C++风格)。
2.类体前必须加上///描述，否则会产生警告【Compound 类名 is not documented】
描述中最好不要带有此类的类名，否则会产生两个链接(但指向同一个文件)影响美观。
3.public和protected会自动生成，但是private要在Expert的Build选项里勾中EXTRACT_PRIVATE，static成员也是如此。
4.函数注释方式
/// Constructor【函数描述】
/// @param [in] pos The position of Camera in world coordinate 【参数描述1】
/// @param [in] lookat The point Camera looks at in world coordinate 【参数描述2】
BaseCamera( const D3DXVECTOR3& pos, const D3DXVECTOR3& lookat );
5.变量注释方式
D3DXVECTOR3 m_Position; /*!< Camera position point in world coordinate */ 或
D3DXVECTOR3 m_Position; ///< Camera position point in world coordinate
两种方式产生的结果不同。前者会单独产生一块Member Data Documentation注释，后者会在Pubilc/Protected/Private Attributes变量描述后紧跟注释。
6.@参数和\参数相同
7.产生描述顺序和注释顺序相同，一般风格为
/// 函数描述
/// @param 参数描述
/// @return 返回值描述
/// @retval 返回值1 返回值1描述
/// @retval 返回值2 返回值2描述
/// @remarks 注意事项
/// @note 注意事项，功能同@remarks,显示字样不同
/// @par 自定义图块，后面可跟示例代码之类
/// @code(必须使用@endcode结束)
/// 示例代码(无需缩进)
/// @endcode
/// @see 其他参考项【产生指向参考的链接】
函数代码声明
8.特殊符号
/// - 产生一个黑色圆点
9.定义在类体里面的enum
/// Camera types
enum CAMERA_TYPE
{
CAMERA_FIRST_VIEW,/*!< Camera that looks from the first view */
CAMERA_MODEL_VIEW,///< Camera that looks from the third view
};
两种风格相同。
以下开始的项都是全局非类内定义，在文件最开始(我尝试是在include之前) 必须加上【/// \file 文件名】，否则不会生成注释【没有File Member页】。
10. 定义在文件里面的宏
#define CAMERA_TYPE_NUMBER ///< The number of camera types. 或
#define CAMERA_TYPE_NUMBER /*!< The number of camera types. */
风格说明见5。
11. 非类内enum定义同10. 两种风格相同。见9。
12. 非类内typedef定义同10. 风格说明见5。
-----------------------------------------------------------
Doxygen
因为代码量大，有些东西前面写后面忘，需要一些注释，而不规范、无结构的注释起不了大作用，因此选用鼎鼎大名的doxygen.
1.setup 直接选用xp 的 binary。因为暂时还没有其它需要，所以没有下载若干辅助软件。
2.documenting the code
注释被分为三类: brief description and detailed description for code item, and in body description.
Detailed descripting way:
1. /**..
* As Visual Assist X supplies. JavaDoc Style
*/
2.
/*!
* Qt Style
*/
3
///(!)
///(!)
///(!)
Some people like to make their comment blocks more visible in the documentation. For this purpose you can use the following:
/********************************************//** * ... text ***********************************************/(note the 2 slashes to end the normal comment block and start a special comment block).
or
///////////////////////////////////////////////// /// ... text ... /////////////////////////////////////////////////
Brief descripting:
-
One could use the\briefcommand with one of the above comment blocks. This command ends at the end of a paragraph, so the detailed description follows after an empty line.
Here is an example:
/*! \brief Brief description. * Brief description continued. * * Detailed description starts here. */
-
IfJAVADOC_AUTOBRIEFis set to
YESin the configuration file, then using JavaDoc style comment blocks will automatically start a brief description which ends at the first dot followed by a space or new line. Here is an example:/** Brief description which ends at this dot. Details follow * here. */
The option has the same effect for multi-line special C++ comments:
/// Brief description which ends at this dot. Details follow /// here.
-
A third option is to use a special C++ style comment which does not span more than one line. Here are two examples:
/// Brief description. /** Detailed description. */
or
//! Brief description. //! Detailed description //! starts here.
Here is an example of a documented piece of C++ code using the Qt style:
//! A test class.
/*!
A more elaborate class description.
*/
class Test
{
public:
//! An enum.
/*! More detailed enum description. */
enum TEnum {
TVal1, /*!< Enum value TVal1. */
TVal2, /*!< Enum value TVal2. */
TVal3 /*!< Enum value TVal3. */
}
//! Enum pointer.
/*! Details. */
*enumPtr,
//! Enum variable.
/*! Details. */
enumVar;
//! A constructor.
/*!
A more elaborate description of the constructor.
*/
Test();
//! A destructor.
/*!
A more elaborate description of the destructor.
*/
~Test();
//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa Test(), ~Test(), testMeToo() and publicVar()
*/
int testMe(int a,const char *s);
//! A pure virtual member.
/*!
\sa testMe()
\param c1 the first argument.
\param c2 the second argument.
*/
virtual void testMeToo(char c1,char c2) = 0;
//! A public variable.
/*!
Details.
*/
int publicVar;
//! A function variable.
/*!
Details.
*/
int (*handler)(int a,int b);
}
觉得这个例子中的注释方式不错：不用敲太多次键盘，决定选用这种。
Putting documentation after members
If you want to document the members of a file, struct, union, class, or enum, and you want to put the documentation for these members inside the compound, it is sometimes desired to place the documentation block after the member instead of before. For this purpose you have to put an additional < marker in the comment block. Note that this also works for the parameters of a function.
Documentation at other places
上面说的都是在代码块前面放注释，Doxygen也允许在其它任何地方注释，但代价是要使用结构化命令。
Structural commands (like all other commands) start with a backslash (\), or an at-sign (@) if you prefer JavaDoc style, followed by a command name and one or more parameters. For instance, if you want to document the classTestin the example above, you could have also put the following documentation block somewhere in the input that is read by doxygen:
/*! \class Test
\brief A test class.
A more detailed class description.
*/
Here the special command\classis used to indicate that the comment block contains documentation for the classTest. Other structural commands are:
-
\structto document a C-struct. -
\unionto document a union. -
\enumto document an enumeration type. -
\fnto document a function. -
\varto document a variable or typedef or enum value. -
\defto document a #define. -
\typedefto document a type definition. -
\fileto document a file. -
\namespaceto document a namespace. -
\packageto document a Java package. -
\interfaceto document an IDL interface.
To document a member of a C++ class, you must also document the class itself. The same holds for namespaces. To document a global C function, typedef, enum or preprocessor definition you must first document the file that contains it (usually this will be a header file, because that file contains the information that is exported to other source files).
Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), youmustdocument the file in which they are defined. In other words, theremustat least be a
/*! \file */
or a
/** @file */
line in this file.
例子：
/*! \file structcmd.h
\brief A Documented file.
Details.
*/
/*! \def MAX(a,b)
\brief A macro that returns the maximum of \a a and \a b.
Details.
*/
/*! \var typedef unsigned int UINT32
\brief A type definition for a .
Details.
*/
/*! \var int errno
\brief Contains the last error code.
\warning Not thread safe!
*/
/*! \fn int open(const char *pathname,int flags)
\brief Opens a file descriptor.
\param pathname The name of the descriptor.
\param flags Opening flags.
*/
/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.
\param fd The descriptor to close.
*/
/*! \fn size_t write(int fd,const char *buf, size_t count)
\brief Writes \a count bytes from \a buf to the filedescriptor \a fd.
\param fd The descriptor to write to.
\param buf The data buffer to write.
\param count The number of bytes to write.
*/
/*! \fn int read(int fd,char *buf,size_t count)
\brief Read bytes from a file descriptor.
\param fd The descriptor to read from.
\param buf The buffer to read into.
\param count The number of bytes to read.
*/
#define MAX(a,b) (((a)>(b))?(a):(b))
typedef unsigned int UINT32;
int errno;
int open(const char *,int);
int close(int);
size_t write(int,const char *, size_t);
int read(int,char *,size_t);
但这么复杂的用法我应该不会用到，因为这些注释目前只有我一个人会去看。。
而且，我目前只要写注释就够了，至于产生为各种格式的文档是以后的事情，因此配置之后可用时再补上。
Doxygen简单经验谈
Doxygen简单经验谈
Doxygen， 大名鼎鼎的文档生成工具，被Boost、OpenCasCade等诸多项目作为文档生成的不二人选。人说，才华横溢往往是高深莫测，这句话放在 Doxygen这里显然是不适用的。十八般武艺样样精通的Doxygen，却十分的简单易用，从头到尾看一下它随机的文档，想不会用都难。。。
嫌看英文麻烦的，这里有一篇中文的入门介绍。 简单的说，如果你准备在项目中采用Doxygen作为文档生成的工具，首先，你需要了解，Doxygen需要什么样的代码结构才能够生产文档。 Doxygen基本上对光秃秃的代码不感兴趣，你需要在所有的类、函数、成员函数、公共变量、名字空间等代码已有表示的结构上方添加上指定格式的注 释，Doxygen才能识别出来。此外，你还可以按照指定格式的注释添加附加的信息，用以生成模块的分类，架构图之类的信息。Doxygen支持的注释格 式多种多样，强烈建议制定一个统一的标准，否则会给项目中其他的人员或者后来的人员带来很多的困扰。。。
Doxygen通常是用作生成英文文档的，生成中文文档需要修改输入和输出的码制，这样可以改变解析方式，生成中文文档。但是，你必须意识 到，Doxygen在从注释中抽取信息是需要做语法解析的，这些解析都是基于英文的基础，不可能在这个层面上支持中文。比如，一个类的简明信息和详细信息 的分隔，是通过英文的句号“.”来识别的，如果你用中文的句号“。”，Doxygen就分辨不出来了。再比如，在某个类的注释中，你写 Created by xxx function，其中xxx是某个方法名，Doxygen会在生成的文档中，自动为该函数添加上链接。当如果你用中文：该类是被xxx方法构造出来的。 Doxygen就无法抽取出该信息并添上链接。你要按如下 格式来写：该类是被 xxx 方法构造出来的。用强行的人肉空格帮助Doxygen。所有类似的问题都可以以此类推。。。
我们说，Doxygen无法识别光秃秃的代码信息，这并不意味着代码结构对Doxygen来说不重要。Doxygen可以对各种语言书写的代码进行优化， 比如你开启C++代码优化后，Doxygen会解析你写的C++代码，添加更多更具体的信息，并依照之间联系为你添加链接。这也就是说，Doxygen会 产生真实的代码结构表示出来的东西，你在写注释的时候也应该按照严谨的代码结构去写。比如，你在某个类A的注释中写道：此类用到了 B 类中的方法。假设B这个类，在名字空间N1内，如果，你的A类同样也是在N1内，这个链接Doxygen会为你自动添加，但是，如果B这个类在名字空间 N2内，Doxygen会无视你的请求。你必须严格的写它的全名 N2::A，Doxygen才会欣然接受这个娃。。。
我在做的项目比较小，因此我利用Doxygen的ToDo-List和Bug列表对项目进行简单的管理。比如，有一个类你有一些后续的工作没有完成，你可 以在其注释中加上@todo xxx，（这只是其中一种语法，不是唯一的规范...）Doxygen会将其链接添加到一个to do list中，并为该to do list生成一个页面，查看起来颇为方便。同样，Bug标记也是这么用这么看的，举一反三大家都会，我就不多磨叽了。。。
Doxygen中利用到很多第三方的基于编译的信息生成工具，辅助生成更为炫目的文档。比如，你可以在注释中嵌入符合tex标准的公式，Doxygen帮助你把这些显示到你的文档中来；你还可以为你的文档自动生成继承图，组合图，UML格式的图，等品种齐全的图，只要你把Graphviz装 上，并打开相关参数即可。更漂亮的是，利用Graphviz的dot方法，你可以将符合其格式的画图指令写在注释中，场景图，架构图，流图，交互图，隔壁 校长含泪跳楼图，只要你能用Graphviz画出，Doxygen都能给你用上，图例想改就改想变就变，幸福生活，不过尔尔。而关于Graphviz，g9老大已经推荐过 了，再多的好话也就显得苍白。这东西无疑是好东西，方便的一塌糊涂，对于常年和代码打交道对直观之物缺失判断的程序员而言，这无疑是居家旅行杀人必备的水 果刀。但要把水果刀玩的和关公大刀似的，是需要不俗功力的，像我这样三脚猫的功夫，就只能关注功能而无法挑战美观了。。。
其他的信息，比如author，date，group，之类的，我都会要求写注释的时候加上，举手之劳，可以方便很多后续可能出现的问题。每一个简单到无 需注释的函数，也要加一个空的注释头，以便生成文档的时候，所有的方法都齐备；如果有需要，你可以修改配置文件的设置，把代码也绑定进文档，这样别人只要 拿着文档一看，几乎就完全不用在添一份代码放在手上了。。。
把文档与代码绑定在一起，这是用Doxygen之类工具的一个好处，它至少可以产生两个方面的生产力。一方面，它可以帮助你构建结构良好的文档，生成真正 可看好看的文档来；另一方面，它可以刺激你更新文档，把文档工具当作项目管理工具用起来。当然，如果文档就在你写的代码上面两行你都懒的看一眼，那么，啥 工具也挽救不了了。用这类工具，必须要文档代码配合着写，配合着看，把它提升到和写单元测试一个习惯级别来，看一眼注释，写一段代码，然后测一测，改改过 期注释，就像蘸酱卷饼吃黄瓜一样一气呵成，那么，Doxygen就可以今夜做梦也会笑了。。。
C++ 程序文档生成器介绍(doxygen)
程序文档，曾经是程序员的一个头痛问题。写一个程序文档，比较花时间，但不是很难；麻烦的是当程序修改后，程序文档也要跟着同步更新，否则文档和程序就要脱节，文档也就变成没用的东西了。好在有许多好用的文档生成器来解决这个问题。目前比较流行的C++文档生成器是doxygen。
本文就简单的介绍一下doxygen的文档注释方法，以供初学者参考：
C++ 程序文档生成器介绍(doxygen)沐枫网志
*@defgroup模块名模块的说明文字
*@name分组说明文字
*分行的简要说明\n
*简要的函数说明文字
*打开文件\n
* A list of events:
* - mouse events
* -# mouse move event
* -# mouse click event\n
* More info about the click event.
* -# mouse double click event
* - keyboard events
* -# key down event
* -# key up event
*
* More text here.
*/
结果为：
A list of events:
- mouse events
- mouse move event
- mouse click event
More info about the click event. - mouse double click event
- keyboard events
- key down event
- key up event
More text here.
/*
*@defgroupEXAMPLES自动注释文档范例*@author沐枫*@version1.0*@date2004-2005*@{
*/
/**@name文件名常量*@{*/
/**日志文件名*/
#define
LOG_FILENAME"d:\\log\\debug.log"
/**数据文件名*/
#define
DATA_FILENAME"d:\\data\\detail.dat"
/**存档文件名*/
#define
BAK_FILENAME"d:\\data\\backup.dat"
/**@}*/
//
文件名常量
/**@name系统状态常量*@{*/
/**正常状态*/
#define
SYS_NORMAL0
/**故障状态*/
#define
SYS_FAULT1
/**警告状态*/
#define
SYS_WARNNING2
/**@}*/
//
系统状态常量
/**枚举常量*/
typedef
enum
TDayOfWeek
{
SUN=0,/**<星期天*/MON=1,/**<星期一*/TUE=2,/**<星期二*/WED=3,/**<星期三*/THU=4,/**<星期四*/FRI=5,/**<星期五*/SAT=6/**<星期六*/}
/**定义类型TEnumDayOfWeek*/
TEnumDayOfWeek;
/**定义类型PEnumDayOfWeek*/
typedefTEnumDayOfWeek
*
PEnumDayOfWeek;
/**定义枚举变量enum1*/
TEnumDayOfWeekenum1;
/**定义枚举指针变量enum2*/
PEnumDayOfWeekp_enum2;
/**@defgroupFileUtils文件操作函数*@{*/
/**打开文件\n*文件打开成功后，必须使用::CloseFile函数关闭。*@param[in]file_name文件名字符串*@param[in]file_mode文件打开模式字符串，可以由以下几个模块组合而成：*-r读取*-w可写*-a添加*-t文本模式(不能与b联用)*-b二进制模式(不能与t联用)*@return返回文件编号*--1表示打开文件失败*@note文件打开成功后，必须使用::CloseFile函数关闭*@par示例:*@code//用文本只读方式打开文件intf=OpenFile("d:\\test.txt","rt");*@endcode*@see::ReadFile::WriteFile::CloseFile*@deprecated由于特殊的原因，这个函数可能会在将来的版本中取消。*/
int
OpenFile(
const
char
*
file_name,
const
char
*
file_mode);
/**读取文件*@param[in]file文件编号，参见：::OpenFile*@param[out]buffer用于存放读取的文件内容*@param[in]len需要读取的文件长度*@return返回读取文件的长度*--1表示读取文件失败*@pre\efile变量必须使用::OpenFile返回值*@pre\ebuffer不能为NULL*@see::OpenFile::WriteFile::CloseFile*/
int
ReadFile(
int
file,
char
*
buffer,
int
len);
/**写入文件*@param[in]file文件编号，参见：::OpenFile*@param[in]buffer用于存放将要写入的文件内容*@param[in]len需要写入的文件长度*@return返回写入的长度*--1表示写入文件失败*@pre\efile变量必须使用::OpenFile返回值*@see::OpenFile::ReadFile::CloseFile*/
int
WriteFile(
int
file,
const
char
*
buffer,
int
len);
/**关闭文件*@paramfile文件编号，参见：::OpenFile*@retval0为成功*@retval-1表示失败*@see::OpenFile::WriteFile::ReadFile*@deprecated由于特殊的原因，这个函数可能会在将来的版本中取消。*/
int
CloseFile(
int
file);
/**@}*/
//
文件操作函数
/**@}*/
//
自动注释文档范例
doxygen相关问题
我主要的设置有
现在 wizard对话框中大体设置下,然后
export设置:
project->DOXYFILE_ENCODING=GBK
project->OUTPUT_LANGUAGE=chinese
input->INPUT_ENCODING=GBK
Dot->HAVE_DOT
Dot-> UML_LOOK
Dot->CALL_GRAPH
Dot->CALLER_GRAPH
http://www.fmddlmyy.cn/text21.html
http://blog.csdn.net/fengrx/archive/2009/09/15/4554830.aspx
下载doxygen的binary 包
doxygen下载地址
http://www.10.xdowns.com/uploadFile/2007-7/doxygen.rar
为了使doxygen能够将类图、协作图等加入到文档中，还要下载安装graphviz for win。
graphviz 2.18下载：
http://www.graphviz.org/pub/graphviz/ARCHIVE/graphviz-2.18.exe
全部安装后就可以开始使用了。
运行doxygen wizard.exe
如 果你像我一样希望只通过图形界面运行doxygen的话，请在doxygen的bin目录中运行doxywizard.exe，这时按照doxygen根 目录下的文档（doxygen_manual-1.5.2.chm）中 Doxywizard usage一节的说明设置即可。主要包括，源码路径、工作路径、输出路径等。
点开始，即可生成文档
最后对文档生成过程中遇到的一些问题进行说明：
1 中文问题：中文注释在文档中是乱码。
解决：在expert中的INPUT选项页的INPUT_ENCODEING中填入“GB2312”，这样基于GB的文本编辑器生成的代码就可以正常使用了。
但是，还有一个无法彻底解决的问题就是，当输出语言为中文时左边的导航栏的所有中文仍然是乱码。哪位有解决方案，请务必告知！
2 图形问题：无法绘制类图协作图等图形。
首 先确保安装了graphviz for win，注意不是wingraphviz，后者是一个graphviz的com封装，但是doxygen并不是基于它开发的，所以装了也没用。然后在 expert的DOT_PATH中填入graphviz的安装路径。接着在wizard的diagram中选择需要生成的图形类别就可以了。
如果出现无法包含.map文件的错误，可以将工作目录设置成html，并将html中所有文件都清除再试。这个问题的原因还不太确定。
3 输出chm的问题：如何输出.chm文件
1. 你必须安装微软或其相兼容的chm编译系统。通常为HTML Help Workshop。
2. 首先在[Wizard...]的Output页面中，选择HTML，然后选择到prepare for compressed HTML(.chm)。
3. 其次在[Expert...]的HTML页面中，将HHC_LOCATION指向微软的hhc工具。通常为C:/Program Files/HTML Help Workshop/hhc.exe。然后点击OK，保存，编译即可。
HHC_LOCATION中输入hhc.exe文件的路径。hhc.exe可以通过安装HTML Help Workshop获得。
HTML Help Workshop 地址：
4 如何像MSDN那样在左边的树中显示函数列表？
打开[Expert...]的HTML页面，然后选中TOC_EXPAND即可。
5 如何去掉CHM附带的CHI文件？
注 意在默认情况下，CHM会有一个CHI文件，似乎是用来加速索引的。我本人也遇到过很多用户仅仅上传了CHM，而没有上传CHI文件，导致无法正常显示的 情况。我不知道是否可以通过工具重建CHI文件，但是我觉得关闭这个功能即可。打开[Expert...]的HTML页面，取消GENERATE_CHI 即可。
6 如何像MSDN那样右边每页显示一个函数？
这个问题其实比较棘手，在[Expert...]中的 Project页面，下面有一个选项叫做SEPARATE_MEMBER_PAGES，把这个选项选中，这样每个函数就是一个页。但是会有一个问题，那就 是右边页面的旁边多了所有函数的列表。很遗憾，经过研究，这个确实无法去掉。我的解决方法就是自己编译一下doxygen，在 memberlist.cpp的writeDocumentationPage函数中将 container->writeQuickMemberLinks(ol,md);连同附近几行屏蔽掉即可。
7 如何在CHM中去掉当选择SUBGROUPING后去掉分组的组信息？
这 个功能就是在chm的左边树中直接列出函数列表，而不用点击看右边页面了。这个功能需要修改源代码。在index.cpp中，屏蔽 writeGroupIndexItem函数的 Doxygen::indexList.addContentsItem，Doxygen::indexList.incContentsDepth和 Doxygen::indexList.decContentsDepth();即可，具体不解释了，一看便知。
8 如何修改或者去掉右下脚Generated at ...的文字？
打 开[Expert...]的HTML页面，然后在HTML_FOOTER中指定相应的HTML文件即可。注意HTML_FOOTER中至少包含BODY和 HTML结束标记。即一个最小的尾部HTML至少是这样</BODY></HTML>。同理，如果你要指定了 HTML_HEADER，他至少包含<HTML><HEAD></HEAD><BODY>
9 如何生成组？
组 就是可以把同类的函数放到一个根下的显示方式。doxygen支持grouping，即你可以把相关的代码通过标志，放到同一个组中，便于查看。这主要是 通过几个内置语法命令。首先通过@defgroup定义一个组，然后要把分组的函数或者类等，通过标志@ingroup加入相应的组。这样，相应的函数就 被放置在同一个组中。
10 如何生成中文帮助？
点击[Expert...]，在页Project 的OUTPUT_LANGUAGE，选择Chinese，这样输出的帮助提示信息就是中文。具体中文提示信息的文字在源代码中。
11 如何彻底解决DoxyGen的输出中文chm的乱码问题？
DoxyGen的实现中大概有三处编码的设置。首先是，doxyfile，也就是配置文件。其次，INPUT_ENCODING，也就是DoxyGen需要解析的输入文件的编码。最后，就是输出的编码。譬如CHM左边的索引编码。
首 先是chm的标题乱码，这个比较好解决，因为DoxyWizard使用QT做的界面，它内部做了转换，所以在DoxyWizard中输入中文，在保存的时 候，他自己做了转码，导致doxyfile中的最终的保存信息不正确。这个时候只需要用记事本打开doxyfile配置文件，输入相应中文即可。注意保存 的时候保存成ANSI编码即可。保存成其他格式的话可能需要去掉BOM，比较麻烦，没研究了。这个相应的编码设置在[Expert...]中，页 Project 的 DOXYFILE_ENCODING，不输入或者默认为UTF-8都行。
其次是右边内容乱码，这个多半是因为你没 有配置好输入的文件编码类型造成的。在[Expert...]的Input页面中，有一个INPUT_ENCODING，这个选项表示输入文件的编码方 式，这要和你处理的源文件格式一致。对于我们来说（使用vs的人），一般设置为GB2312。当然，再次声明，编码方式取决于源文件的编码方式。如果文件 编码已经是UTF-8了，然而你还将其设置成GB2312，那么DoxyGen会将UTF-8当成ANSI再进行一次UTF-8转换，自然会出错了。
最 后也是经常遇到的问题就是DoxyGen生成的CHM文件的左边树目录的中文变成了乱码。这个只需要将chm索引的编码类型修改为GB2312即可。在 HTML的CHM_INDEX_ENCODING中输入GB2312即可。然而这种方法下，还有一个瑕疵之处，就是chm的搜索页的搜索结果中显示的中文 文字却变成乱码了。这是因为DoxyGen默认开启了HTML Help Workshop的Full-text search全文搜索选项，他在进行全文搜索的时候，应该是打开文件然后按照ANSI进行搜索的，（资料表示HHW不支持UTF-8，仅支持ISO- 8859-1或者windows-1252编码。）而Doxygen生成的右边界面统一是UTF-8，这自然出现了问题。而在这种情况下做全文搜索，理论 上只能搜索英文。
无奈，我们的解决方案只能是重新编译DoxyGen代码，为了满足搜索，只要保证右边的页面文件不是UTF-8即可。 我们首先修改writeDefaultHeaderFile这个函数的代码，将其charset=GB2312。然后在 TranslatorDecoder的构造函数中修改m_toUtf8 = (void*)-1;即屏蔽文本写入时最终的转换函数。最后删除INPUT_ENCODING的设置或者输入UTF-8。这样会使DoxyGen认为我们 的文本是UTF-8的，从而不用进行转换。生成替换原始的DoxyGen即可。
另外需要补充的是，还有一种方案是不用修改作者的源代码，但是需要将DoxyGen生成的右边的HTML文件使用工具（如iconv）手工转换成GB2312，然后再使用HTML Help Workshop生成，网上有篇文章介绍过，我测试一下，也是没有问题的。
最后，doxygen是一个开源项目，并且支持vs2005项目，这样一来，如果你觉得哪里不顺手，完全可以把代码下载后自行编译。虽然我感觉doxygen的代码写的不能算是perfect，但是对于一个这样的工程，我们无论如何都需要一种敬意。祝好运~
这样，基本上就能够用doxygen生成漂亮的文档了。代码方面，doxygen支持多种格式的注释风格，根据manual选择自己喜欢的就好。
相关参考：