Posted on 2009-12-24 16:36
Prayer 閱讀(750)
評論(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