Posted on 2009-12-24 16:36
Prayer 阅读(711)
评论(0) 编辑 收藏 引用 所属分类:
面向对象
Doxygen是这样的一个工具，在我们写代码的同时，加上特定的注释，然后，Doxygen就利用这些注释生成漂亮的程序文档。
Doxygen是GPL众多优秀软件中的一员，当然，不仅仅在Linux平台有Doxygen，Doxygen还有Windows版本，而且他还提供了一个图形界面Doxywizard,使得使用Docxygen 更加方便。
按照Doxywizard的步骤，
首先，我们要生成配置文件，可以采用简单的方式，比如点击wizard按钮，配置好工程名(Project Name),工程的版本号，源文件的位置，以及代码文档的配置，其他默认，就可以简单地配置好一个C++环境的Docxyfile，而以这个为模板就可以生成相应的文档了；又或者点击Expert，可以更详细地配置Doxyfile，（注意，在expert选项里面可以选择中文生成中文文档）。
第二步，保存Doxyfile；第三步，选择工作目录；剩下的就是点击start生成文档了；
生成的文档可以有html,或latex以及其他例如RTF，xml。不过中文latex的话就要加相应的宏包。
说完Docxygen的使用方法，马上就要说说Doxygen的注释的写法，毕竟注释才是Doxygen生成文档的依据。
注释块可以是以下形式
1
/**//**
2
* 
文本
3
*/
4
或
5/**//*!
6 * 文本
7 */
8或
9/**//*!
10 文本
11*/
可以在注释块中加入下列元素来提示Docxygen来生成文档，
1\struct 产生一个C语言的struct
2\class 产生一个类的文档
3\union 产生一个联合体的文档
4\enum 产生一个枚举类型的文档
5\fn 函数
6\var 变量
7\def #define 宏
8\typedef 类型定义
9\file 文件
10\namespace 命名空间
11\parm 函数的变量的注释
12\return 函数的返回值的注释
13\sa 参看
14\see 参考
不过以上的元素只是在注释块为
或
时才有效，而使用“@元素名”在
中是有效的。
还有可以利用"f[和"f]以及他们中间的LaTeX代码生成一个行间居中对齐的数学公式，或利用"f$和"f$以及LaTeX代码来生成数学公式。
下面来一个例子，（Doxygen帮助里的一个例子）
1/**//*! "file structcmd.h
2 "brief A Documented file.
3
4 Details.
5*/
6
7/**//*! "def MAX(a,b)
8 "brief A macro that returns the maximum of "a a and "a b.
9
10 Details.
11*/
12
13/**//*! "var typedef unsigned int UINT32
14 "brief A type definition for a .
15
16 Details.
17*/
18
19/**//*! "var int errno
20 "brief Contains the last error code.
21
22 "warning Not thread safe!
23*/
24
25/**//*! "fn int open(const char *pathname,int flags)
26 "brief Opens a file descriptor.
27
28 "param pathname The name of the descriptor.
29 "param flags Opening flags.
30*/
31
32/**//*! "fn int close(int fd)
33 "brief Closes the file descriptor "a fd.
34 "param fd The descriptor to close.
35*/
36
37/**//*! "fn size_t write(int fd,const char *buf, size_t count)
38 "brief Writes "a count bytes from "a buf to the filedescriptor "a fd.
39 "param fd The descriptor to write to.
40 "param buf The data buffer to write.
41 "param count The number of bytes to write.
42*/
43
44/**//*! "fn int read(int fd,char *buf,size_t count)
45 "brief Read bytes from a file descriptor.
46 "param fd The descriptor to read from.
47 "param buf The buffer to read into.
48 "param count The number of bytes to read.
49*/
50
51#define MAX(a,b) (((a)>(b))?(a):(b))
52typedef unsigned int UINT32;
53int errno;
54int open(const char *,int);
55int close(int);
56size_t write(int,const char *, size_t);
57int read(int,char *,size_t);
以及一个对类的注释（注意里面对成员变量的注释）
1/**//**
2 * A test class. A more elaborate class description.
3 */
4
5class Test
6{
7 public:
8
9
/**//**
10 * An enum.
11 * More detailed enum description.
12
*/
13
14 enum TEnum {
15 TVal1, /**//**< enum value TVal1. */
16 TVal2, /**//**< enum value TVal2. */
17 TVal3 /**//**< enum value TVal3. */
18 }
19 *enumPtr, /**//**< enum pointer. Details. */
20 enumVar; /**//**< enum variable. Details. */
21
22 /**//**
23 * A constructor.
24 * A more elaborate description of the constructor.
25 */
26 Test();
27
28 /**//**
29 * A destructor.
30 * A more elaborate description of the destructor.
31 */
32 ~Test();
33
34 /**//**
35 * a normal member taking two arguments and returning an integer value.
36 * @param a an integer argument.
37 * @param s a constant character pointer.
38 * @see Test()
39 * @see ~Test()
40 * @see testMeToo()
41 * @see publicVar()
42 * @return The test results
43 */
44 int testMe(int a,const char *s);
45
46 /**//**
47 * A pure virtual member.
48 * @see testMe()
49 * @param c1 the first argument.
50 * @param c2 the second argument.
51 */
52 virtual void testMeToo(char c1,char c2) = 0;
53
54 /**//**
55 * a public variable.
56 * Details.
57 */
58 int publicVar;
59
60 /**//**
61 * a function variable.
62 * Details.
63 */
64 int (*handler)(int a,int b);
65};
生成的文档如例一/Files/lyq105/refman1.pdf
以及 /Files/lyq105/refman2.pdf