doxygen如何生成JAVA文档_有用Doxygen生成文档的吗？发一篇Doxygen的使用文档给大家，从网上搜来的。...
第二章：Documenting the code
特殊的注釋
一種特殊的注釋是帶有一些額外標記的C/C++注釋塊，這樣doxygen就知道需要將其加入到文檔中了。
對于每個代碼塊都有兩種注釋，這兩種注釋組成了文檔：一種是brief 描述另一種是detailed 描述，都是可選的。可以有多于一個的brief 描述和detailed 描述，但是是無效的。
顧名思義，一個brief描述只有一行，而detail描述則是更長更詳盡的文檔。
有幾種方式添加一個detail描述：
1.??使用JavaDoc風格，包含一個C風格的注釋塊
/**
* ... text ...
*/
2.??使用Qt風格
/*!
* ... text ...
*/
這中間的*都是可選的，因此
/*!
... text ...
*/
也是有效的
3.??第三種風格是至少使用兩個C++注釋行，每行加多一個/或者是!
///
/// ... text ...
///
或
//!
//!... text ...
//!
4.? ???有些人喜歡將注釋變得比較醒目，可以這樣來作
/
/// ... text ...
/
有以下方式添加brief注釋
1.??一種是在上述注釋塊中使用\brief，然后一個空行后跟著Detail注釋
/*! \brief Brief description.
*? ?? ?? ?Brief description continued.
*
*??Detailed description starts here.
*/
2.??如果配置文件中JAVADOC_AUTOBRIEF被設為YES，則使用JavaDoc風格注釋塊將自動開始一個brief注釋，這個注釋將以“.”后跟一個空格或新行結束
/** Brief description which ends at this dot. Details follow
*??here.
*/
同樣可以應用到多行的C++風格注釋中
/// Brief description which ends at this dot. Details follow
/// here.
3.??第三種可以使用一種特殊的C++風格注釋，每次不超過一行
/// Brief description.
/** Detailed description. */
或
//! Brief descripion.
//! Detailed description
//! starts here.
注意后一個例子中的空行，Doxygen用他來分開brief描述和detail描述。在此情況下JAVADOC_AUTOBRIEF也應設置為NO
如你所見，doxygen很靈活，下面這種寫法是非法的
//! Brief description, which is
//! really a detailed description since it spans multiple lines.
/*! Oops, another detailed description!
*/
因為doxygen只允許一個brief和一個detail描述
更進一步，如果一個brief描述在 declaration前，一個在code前，那么將使用declaration前的那個。對于detailed描述也是如此，definition前的那個比declaration前的有高優先級。
這里有一段Qt風格的C++例子：(注意這一段需要仔細研究，改寫掉注釋宏的代碼)
//!??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 return 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);
};
這些單行注釋包括一個brief描述，而multi-line注釋塊包含一個更詳細的描述。
Brief描述包含在class，namespace或file的member的預覽中，小號的斜體字(通過將BRIEF_MEMBER_DESC設置為NO可以關掉這些brief描繪)。缺省的brief描述是detailed描述的第一句話(通過將REPEAT_BRIEF設置為NO可以改變此設置)。在Qt風格中brief和detailed都是可選
缺省的，JavaDoc風格的注釋塊和Qt風格的注釋同樣有效。這并不是根據JavaDoc規格的，而是注釋的第一行被認為是brief描述。要打開此設置，將JAVADOC_AUTOBRIEF設置為YES。用一個“.”來作分隔，或者使用一個“\”：
/** Brief description (e.g.\ using only a few words). Details follow. */
設置JavaDoc style和JAVADOC_AUTOBRIEF為YES:
/**
*??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. */
}
*enumPtr, /**< enum pointer. Details. */
enumVar;??/**< enum variable. Details. */
/**
* 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 & return an integer value.
* @param a an integer argument.
* @param s a constant character pointer.
* @see Test()
* @see ~Test()
* @see testMeToo()
* @see publicVar()
* @return The test results
*/
int testMe(int a,const char *s);
/**
* A pure virtual member.
* @see 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);
};
和大多數文檔系統不一樣，doxygen也允許你將將member注釋放在definition之前。這種方式下，注釋可以寫在.cpp文件中而非.h文件中。這樣頭文件就顯得比較簡潔，同時member前也直接有注釋。作為一種妥協，brief描述可以放在member的declaration前，detailed描述可以放在definition前。
在members之后添加注釋
如果需要為file，struct，union，class或enmu的members添加注釋，并且你需要將這些注釋放在compound之內，可以考慮將注釋塊放在member的后面。這樣就要在注釋塊中添加一個“
下面是個例子：
int var; /*!< Detailed description after the member */
這個塊在用來在在一個member之后添加一個注釋塊(Qt風格)
還有一種方式
int var; /**< Detailed description after the member */
或者是
int var; //!< Detailed description after the member
//!<
或者是
int var; ///< Detailed description after the member
///<
多數情況下只是需要在一個member后添加一個brief描述，如下：
int var; //!< Brief description after the member
或者
int var; ///< Brief description after the member
注意這些塊有相同的結構，不過是使用了
這里有個使用注釋塊的例子：
/*! A test class */
class Test
{
public:
/** An enum type.
*??The documentation block cannot be put after the enum!
*/
enum EnumType
{
int EVal1,? ???/**< enum value 1 */
int EVal2? ?? ?/**< enum value 2 */
};
void member();? ?//!< a member function.
protected:
int value;? ?? ? /*!< an integer value */
};
Click here for the corresponding HTML documentation that is generated by doxygen.
警告：
這些塊只能用來給members和parameters注釋。不能用來給files，classes，unions，structs，groups，namespaces和enums添加注釋。還有下一節中論述的structural commands在這種注釋塊中被忽略掉了
Documentation at other places
截止目前，我們談到的注釋塊都是在file，class或namespace的declaration或definition之前還有是在member的前后。盡管這通常已經達到目的，但有時要將注釋放在其他地方。為一個文件添加注釋也是有必要的，但是沒有“在文件之前”這種地方。Doxygen允許將注釋塊放在其他的任何地方(也有不允許的：例如函數體內或一個標準的C-style注釋塊中)。
這樣作比較麻煩的是需要在注釋塊中添加一些structural命令。
Structual commands(像其他的commands)以“\”開頭，或是一個“@”(使用JavaDoc風格)，后面是命令名和一或多個參數。例如，如果你想給上面的Test類添加一個注釋：
/*! \class Test
\brief A test class.
A more detailed class description.
*/
這里特殊命令“\class”用于指出該注釋塊中含有對Test類的注釋。還有一些其他的structural命令：
?\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.
?\file to document a file.
?
amespace to document a namespace.
?\package to document a Java package.
?\interface to document an IDL interface.
參看Special Commands獲得更詳細資料。
為了注釋一個類中的member，首先要對該類作注釋。同樣的問題上升到namespace。要注釋一個全局的function，typedef，enum或preprocessor定義，你需要首先定義包含它的文件(通常情況下是一個.h文件，因為這些文件包含可以export到其他源文件的信息)。
讓我們重復一下，因為常常被忽視：要注釋一個global objects(functions，typedefs， enum，macros等)，必須注釋它們所在的.h文件。換句話，至少要這樣注釋一下
/*! \file */
或這樣一個
/** @file */
行在該文件中
這里用個名為structcmd.h的C頭文件，講解如何使用structal commands。
/*! \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);
Click here for the corresponding HTML documentation that is generated by doxygen.
Because each comment block in the example above contains a structural command, all the comment blocks could be moved to another location or input file (the source file for instance), without affecting the generated documentation. The disadvantage of this approach is that prototypes are duplicated, so all changes have to be made twice! Because of this you should first consider if this is really needed, and avoid structural commands if possible. I often receive examples that contain \fn command in comment blocks which are place in front of a function. This is clearly a case where the \fn command is redundant and will only lead to problems.
因為上例中每個注釋塊都包含一個結構化命令，所有注釋快都可以放在其他位置或input文件(例如source file)，都不會影像文檔的生成。這種做法的缺點是原型被復制了，所以每次都要寫兩遍。因為如此，你應該首先考慮是否有必要，并盡可能避免structural commands。我常常收到含有這種文件，在一個函數前的注釋中有“\fn”命令。這樣是冗余的，導致容易出錯。
總結
以上是生活随笔為你收集整理的doxygen如何生成JAVA文档_有用Doxygen生成文档的吗？发一篇Doxygen的使用文档给大家，从网上搜来的。...的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： java递归 treeview_tree
- 下一篇： oracle挂证多少钱一个月_惊呆，一条