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的文本編輯器生成的代碼就可以正常使用了。

clip_image002

但是，還有一個無法徹底解決的問題就是，當輸出語言為中文時左邊的導航欄的所有中文仍然是亂碼。哪位有解決方案，請務必告知！

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，保存，編譯即可。

clip_image004[1]

HHC_LOCATION中輸入hhc.exe文件的路徑。hhc.exe可以通過安裝HTML Help Workshop獲得。

clip_image006

HTML Help Workshop 地址：

http://www.microsoft.com/downloads/details.aspx?FamilyID=00535334-c8a6-452f-9aa0-d597d16580cc&displaylang=en

4 如何像MSDN那樣在左邊的樹中顯示函數列表？

打開[Expert...]的HTML頁面，然后選中TOC_EXPAND即可。

clip_image008

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，這樣輸出的幫助提示信息就是中文。具體中文提示信息的文字在源代碼中。

clip_image010

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選擇自己喜歡的就好。

相關參考：

http://blog.csdn.net/sfcyyc/archive/2008/07/15/2653683.aspx

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?\brief?command 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.*/
```
If?JAVADOC_AUTOBRIEF?is set to?YES?in 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. */

//! 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 class?Test?in 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?\class?is used to indicate that the comment block contains documentation for the class?Test. Other structural commands are:

\struct?to document a C-struct.
\union?to document a union.
\enum?to document an enumeration type.
\fn?to document a function.
\var?to document a variable or typedef or enum value.
\def?to document a #define.
\typedef?to document a type definition.
\file?to document a file.
\namespace?to document a namespace.
\package?to document a Java package.
\interface?to 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), you?must?document the file in which they are defined. In other words, there?must?at 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，大名鼎鼎的文檔生成工具，被Boost、OpenCasCade等諸多項目作為文檔生成的不二人選。人說，才華橫溢往往是高深莫測，這句話放在 Doxygen這里顯然是不適用的。十八般武藝樣樣精通的Doxygen，卻十分的簡單易用，從頭到尾看一下它隨機的文檔，想不會用都難。。。

?? ? ?嫌看英文麻煩的，這里有一篇中文的入門介紹。簡單的說，如果你準備在項目中采用Doxygen作為文檔生成的工具，首先，你需要了解，Doxygen需要什么樣的代碼結構才能夠生產文檔。 Doxygen基本上對光禿禿的代碼不感興趣，你需要在所有的類、函數、成員函數、公共變量、名字空間等代碼已有表示的結構上方添加上指定格式的注釋，Doxygen才能識別出來。此外，你還可以按照指定格式的注釋添加附加的信息，用以生成模塊的分類，架構圖之類的信息。Doxygen支持的注釋格式多種多樣，強烈建議制定一個統一的標準，否則會給項目中其他的人員或者后來的人員帶來很多的困擾。。。

?? ? ? 按照指定的格式書寫了注釋之后，就需要寫一個Doxygen的配置文件，依照此配置文件，Doxygen可以生產HTML、Tex、XML等多種格式輸出文檔。Doxygen的配置文件，有輔助的GUI工具幫助書寫，你只需要改幾個選項，點幾下按鈕就信手拈來了。但在此強烈建議，你應該把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)?????沐楓網志

1.?模塊定義（單獨顯示一頁）

/*
?*?@defgroup?模塊名?模塊的說明文字

?*?@{

?*/

?... 定義的內容 ...

/**?@}?*/ // 模塊結尾

2.?分組定義（在一頁內分組顯示）

/*
?*?@name?分組說明文字

?*?@{

?*/

?... 定義的內容 ...

/**?@}?*/

3.?變量、宏定義、類型定義簡要說明

/**?簡要說明文字?*/

#define FLOAT float

/**?@brief 簡要說明文字（在前面加 @brief 是標準格式）?*/

#define MIN_UINT 0

/*
?*?分行的簡要說明?\n

?*??這是第二行的簡要說明

?*/

int?b;

4.?函數說明

/*
?*?簡要的函數說明文字?

?*??@param?[in]?param1?參數1說明

?*??@param?[out]?param2?參數2說明

?*??@return?返回值說明

?*/

int?func(int?param1,?int?param2);

/*
?*?打開文件?\n

?*??文件打開成功后，必須使用?::CloseFile?函數關閉。

?*??@param[in]?file_name?文件名字符串

?*??@param[in]?file_mode?文件打開模式字符串，可以由以下幾個模塊組合而成：

?*??-?r?讀取

?*??-?w?可寫

?*??-?a?添加

?*??-?t?文本模式(不能與?b?聯用)

?*??-?b?二進制模式(不能與?t?聯用)

?*??@return?返回文件編號

?*??-?-1?表示打開文件失敗

?*??@note?文件打開成功后，必須使用?::CloseFile?函數關閉

?*??@par?示例:

?*??@code

????//?用文本只讀方式打開文件

????int?f?=?OpenFile("d:\\test.txt",?"rt");

?*??@endcode

?*??@see?::ReadFile?::WriteFile?::CloseFile

?*??@deprecated?由于特殊的原因，這個函數可能會在將來的版本中取消。

?*/

int?OpenFile(const?char*?file_name,?const?char*?file_mode);

5.?枚舉類型定義

/**?枚舉常量?*/

typedef?enum?TDayOfWeek

{

SUN?=?0,?/**< ?星期天（注意，要以 “<” 小于號開頭）?*/

MON?=?1,?/**< ?星期一?*/

TUE?=?2,?/**< ?星期二?*/

WED?=?3,?/**< ?星期三?*/

THU?=?4,?/**< ?星期四?*/

FRI?=?5,?/**< ?星期五?*/

SAT?=?6??/**< ?星期六?*/

}

/**?定義類型?TEnumDayOfWeek?*/

TEnumDayOfWeek;??

6. 項目符號標記

? /*?
?? *? 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
1. mouse move event
2. mouse click event
  More info about the click event.
3. mouse double click event
keyboard events
1. key down event
2. key up event

More text here.

代碼示范：

?*?@defgroup?EXAMPLES?自動注釋文檔范例

?*?@author??沐楓

?*?@version?1.0

?*?@date????2004-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_NORMAL?0

/**?故障狀態?*/

#define?SYS_FAULT?1

/**?警告狀態?*/

#define?SYS_WARNNING?2

/**?@}*/?//?系統狀態常量

/**?枚舉常量?*/

typedef?enum?TDayOfWeek

{

????????SUN?=?0,?/**<?星期天?*/

????????MON?=?1,?/**<?星期一?*/

????????TUE?=?2,?/**<?星期二?*/

????????WED?=?3,?/**<?星期三?*/

????????THU?=?4,?/**<?星期四?*/

????????FRI?=?5,?/**<?星期五?*/

????????SAT?=?6??/**<?星期六?*/

}

/**?定義類型?TEnumDayOfWeek?*/

TEnumDayOfWeek;??

/**?定義類型?PEnumDayOfWeek?*/

typedef?TEnumDayOfWeek*?PEnumDayOfWeek;?

/**?定義枚舉變量?enum1?*/

TEnumDayOfWeek?enum1;????????

/**?定義枚舉指針變量?enum2?*/

PEnumDayOfWeek?p_enum2;?

?*?@defgroup?FileUtils?文件操作函數

?*?@{

?*/

?*?打開文件?\n

?*??文件打開成功后，必須使用?::CloseFile?函數關閉。

?*??@param[in]?file_name?文件名字符串

?*??@param[in]?file_mode?文件打開模式字符串，可以由以下幾個模塊組合而成：

?*??-?r?讀取

?*??-?w?可寫

?*??-?a?添加

?*??-?t?文本模式(不能與?b?聯用)

?*??-?b?二進制模式(不能與?t?聯用)

?*??@return?返回文件編號

?*??-?-1?表示打開文件失敗

?*??@note?文件打開成功后，必須使用?::CloseFile?函數關閉

?*??@par?示例:

?*??@code

????//?用文本只讀方式打開文件

????int?f?=?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?\e?file?變量必須使用?::OpenFile?返回值

?*??@pre?\e?buffer?不能為?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?\e?file?變量必須使用?::OpenFile?返回值

?*??@see?::OpenFile?::ReadFile?::CloseFile

?*/

int?WriteFile(int?file,?const?char*?buffer,?int?len);

?*?關閉文件?

?*??@param?file?文件編號，參見：::OpenFile

?*??@retval?0??為成功

?*??@retval?-1?表示失敗

?*??@see?::OpenFile?::WriteFile?::ReadFile

?*??@deprecated?由于特殊的原因，這個函數可能會在將來的版本中取消。

?*/

int?CloseFile(int?file);

/**?@}*/?//?文件操作函數

/**?@}*/?//?自動注釋文檔范例

生成的chm文檔截圖：

范例下載：
/Files/ly4cn/doxygen_example.rar

http://www.cnblogs.com/ly4cn/archive/2005/11/23/282637.html