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 );

即代码示例在一个地方，在其他地方重用。

这实际上是我所得到的，但我对此不满意，因为我不知道如何隐藏我正在创建并从中复制的虚拟页面“ResourceExampleTag”。因此，在生成的文档中的某处，有一个页面包含一些完全脱离上下文的代码。据我所知，这里的事情是找到一个可以被 copydoc 引用的标签，并且它本身不会呈现任何内容。不过，这只是我的想法，也许还有更好的。

我还可以提到，我（出于多种原因，我不想深入讨论）不希望将 \example 标签与外部示例代码文件一起使用。

谢谢。

Answer 1

这对我有用：

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之前需要有一个空行，否则它不起作用（有时，并不总是......）

Answer 2

我发现 @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 );

...当然，只有在完成答案后，我才意识到您不想使用外部文件，但由于我在尝试执行此处描述的操作时偶然发现了这个问题，它可能对某人有用！

Answer 3

我遇到了同样的问题，也找不到任何优雅的解决方案。我最终提出了以下建议：

1）在某个随机页面上，链接到一个名为“隐藏”的新子页面

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

2）创建隐藏页面，链接到您的“虚拟”示例主题。将页面命名为  

/*! \page Hidden  
    \subpage MyExample
   */

3) 现在您可以在任何地方 \copydoc MyExample，并且对于 doxygen 生成的 HTML 的用户来说，它是不可见的。