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否则它不工作（有时，总是不...）