我想使用\ 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 );
即。代码示例在一个地方,在其他地方重复使用。
这实际上是我已经得到的,但我不满意,因为我不知道如何隐藏我正在创建的虚拟页面'ResourceExampleTag'来复制。所以在结果文档中的某个地方有一个页面,其中一些代码完全脱离了上下文。据我所知,这里的事情是找到一个可以被copydoc引用的标签,它不会自己呈现任何内容。然而,这只是我的思路,可能会有更好的思路。
我还可以提到我(由于几个原因我不打算进入)不希望将\ example标签与外部示例代码文件一起使用。
感谢。
答案 0 :(得分:11)
这对我有用:
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
之前需要一个空行,否则它不起作用(有时候,并不总是......)
答案 1 :(得分:5)
我发现@snippet命令对于创建内联示例更有用,就像您尝试的那样。基本上我有我的示例的源文件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]
然后在函数的doxygen文档块中使用@snippet来使用示例。
/// Aquires resource.
///
/// @par Example:
/// @snippet my_examples.cpp exampleMyFirst
Resource* AquireResource( int id );
...当然只有在完成答案后,我才意识到你不想使用外部文件,但是因为我偶然发现了试图按照我在这里描述的那样做的问题,所以对某些人来说这可能是有用的!
答案 2 :(得分:0)
我有同样的问题,也找不到任何优雅的解决方案。我最终想出了以下内容:
1)在某个随机页面上,链接到名为Hidden
的新子页面/*! \mainpage My MainPage
blah blah blah
\subpage Hidden
*/
2)创建隐藏页面,链接到“虚拟”示例主题。将页面命名为
/*! \page Hidden
\subpage MyExample
*/
3)现在你可以在任何你喜欢的地方\copydoc MyExample
,并且对于doxygen生成的HTML用户来说是不可见的。