Doxygen copydoc標籤重用代碼示例

Question

我想重複使用\ copydoc標籤的示例代碼塊。

解釋問題。比方說，我有兩個記錄功能：

/** Aquires resource. */ 
Resource* AquireResource(int id); 

/** Releases resource.*/ 
void ReleaseResource(Resource* res); 

在許多情況下，我想提出的如何在一個背景下，這往往涉及到使用範圍的所有可能有足夠的功能，使用該功能一個小的代碼示例由相同的代碼示例描述，例如：

/** Aquires resource. 
* 
* \par Example: 
* \code 
* Resource* res = AquireResource(42); 
* ReleaseResource(res); 
* \endcode 
*/ 
Resource* AquireResource(int id); 

/** Releases resource. 
* 
* \par Example: 
* \code 
* Resource* res = AquireResource(42); 
* ReleaseResource(res); 
* \endcode 
*/ 
void ReleaseResource(Resource* res); 

所以代碼示例是重複的，不好。我想要使​​用copydoc，像這樣：

/** \page ResourceExampleTag 
* \code 
* Resource* res = AquireResource(42); 
* ReleaseResource(res); 
* \endcode 
*/  

/** Aquires resource. 
* 
* \par Example: 
* \copydoc ResourceExampleTag 
*/ 
Resource* AquireResource(int id); 

/** Releases resource. 
* 
* \par Example: 
* \copydoc ResourceExampleTag 
*/ 
void ReleaseResource(Resource* res); 

I.e.代碼示例在一個地方，在其他地方重複使用。

這實際上就我所知，但我不滿意它，因爲我不知道如何隱藏我正在創建的虛擬頁面「ResourceExampleTag」。因此，在結果文檔中的某處出現了一些代碼完全不符合上下文的頁面。據我可以看到，這裏的東西是找到一個可以由copydoc引用的標籤，並且它本身不會呈現任何內容。但是，這只是我的思路，可能會有更好的。

我還可以提到我（由於幾個原因，我不打擾進入）不希望對外部示例代碼文件使用\ example標記。

謝謝。

Answer 1

我發現@snippet命令來創建內嵌的例子更有益就像你正在做的那樣。基本上，我在Doxygen文檔塊我的例子源文件，my_examples.cpp

/// [exampleMyFirst] 
void foo(void) 
{ 
    Resource* foo = AquireResource(42); 
    ReleaseResource(foo); 
    foo = nullptr; //Or NULL 
} 
/// [exampleMyFirst] 

/// [exampleTwo] 
void bar(void) 
{ 
    std::cout << "Unrelated to my first example." << std::endl; 
} 
/// [exampleTwo] 

然後您使用的功能，以@snippet使用的例子。

/// Aquires resource. 
/// 
/// @par Example: 
/// @snippet my_examples.cpp exampleMyFirst 
Resource* AquireResource(int id); 

...當然，整理答案後只，做我知道你不想使用外部文件，但因爲我偶然發現了這個問題試圖做什麼，我在這裏所描述的，它可能對某人有用！

Answer 2

我有同樣的問題，無法找到任何優雅的解決方案。我終於想出了以下內容：

1）在一些隨機的網頁，鏈接到一個新的子頁面叫做隱藏

/*! \mainpage My MainPage 
    blah blah blah 
    \subpage Hidden 
    */ 

2）創建隱藏的頁面，鏈接到你的「假」如主題。名稱頁 

/*! \page Hidden   
    \subpage MyExample 
    */ 

3）現在你可以\copydoc MyExample你喜歡的地方，它是無形的doxygen通過生成的HTML的用戶。

Answer 3

這個工作對我來說：

class MyClass 
{ 
    public: 
    /** 
    * @class hide_commonstuff 
    * @par Example: 
    * @code 
    * The common example 
    * @endcode 
    */ 

    /** 
    * First function. 
    * 
    * @copydoc hide_commonstuff 
    */ 
    void first(); 

    /** 
    * Second function. 
    * 
    * @copydoc hide_commonstuff 
    */ 
    void second(); 
}; 

然後在doxygen的配置設置EXCLUDE_SYMBOLS = hide_*

的文檔從hide_commonstuff複製，但這個類是不能在類列表中顯示。

另外：需要有一個空行之前@copydoc否則它不工作（有時，總是不...）