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

...当然只有在完成答案之后,我才意识到你不想使用外部文件,但是因为我偶然发现了试图按照我在这里描述的那样做的问题,这对某人来说可能是有用的!