本節概述了doxygen是什麼,以及開發人員可能想要使用它的原因。
它還應該提到doxygen中的任何大型主題,並鏈接到相關主題。由於doxygen的文檔是新的,您可能需要創建這些相關主題的初始版本。
有幾種方法可以將註釋塊標記為詳細描述,以便Doxygen解析此註釋塊並將其作為以下代碼項的描述添加到文檔中。第一個也是最常見的是C樣式註釋,在註釋開始序列中帶有額外的星號,例如:
/**
* … text …
*/
int dummy_var;
下一個選擇是使用Qt樣式並在C樣式註釋塊的打開序列之後添加感嘆號(!):
/*!
* … text …
*/
void foo(void);
第三種方法是使用至少兩個C ++註釋行的塊,其中每一行以一個額外的斜杠或感嘆號開頭:
///
/// ... text ...
///
要么
//!
//! ... text ...
//!
有些人喜歡在文檔中更明顯地顯示他們的評論塊。為此,您可以使用以下內容:
/********************************************//**
* ... text
***********************************************/
注意2斜杠結束正常註釋塊並啟動一個特殊註釋塊。
/////////////////////////////////////////////////
/// ... text ...
/////////////////////////////////////////////////
為了構建和生成生成的文檔,Doxygen提供了大量(> 170)特殊命令。文檔中的所有命令都以反斜杠()或at符號(@)開頭。
例如
/**
* \brief A brief description in one short sentence.
*/
相當於
/**
* @brief A brief description in one short sentence.
*/
簡要說明還有幾種可能性:
可以將\brief
命令與上述註釋塊之一一起使用。此命令在段落的末尾結束,因此詳細描述在空行之後。
/** \brief Brief description.
* Brief description continued.
*
* Detailed description starts here.
*/
如果配置文件中的JAVADOC_AUTOBRIEF
設置為YES
,那麼使用JavaDoc樣式的註釋塊將自動開始一個簡短的描述,該描述以第一個點結尾,後跟空格或新行。
/// Brief description which ends at this dot. Details follow
/// here.
最後這裡有一個關於doxygen函數的完整文檔的示例:
/**
* \brief The function bar.
*
* \details This function does something which is doing nothing. So this text
* is totally senseless and you really do not need to read this,
* because this text is basically saying nothing.
*
* \note This text shall only show you, how such a \"note\" section
* is looking. There is nothing which really needs your notice,
* so you do not really need to read this section.
*
* \param[in] a Description of parameter a.
* \param[out] b Description of the parameter b.
* \param[in,out] c Description of the parameter c.
*
* \return The error return code of the function.
*
* \retval ERR_SUCCESS The function is successfully executed
* \retval ERR_FAILURE An error occurred
*/
errcode_t bar(int a, int b, int c)
{
/** More detailed description inside the code */
}
來源和Doxygen主頁上的更多信息
有關設置或安裝doxygen的詳細說明。