Doxygen copydoc标签可重用代码示例 [英] Doxygen copydoc tag to reuse code examples

问题描述

我想使用\copydoc标记重用示例代码块。

I want to reuse a block of example code using the \copydoc tag.

解释问题。假设我有两个已记录的函数：

To explain the problem. Let's say I have two documented functions:

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

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

在很多情况下，我想举一个如何在上下文中使用该函数的小代码示例，通常涉及到使用同一代码示例充分描述的一系列功能，例如：

In many cases I want to put in a small code example of how to use the function in a context, which often involves using a range of functions which all might be sufficiently depicted by the same code example, for instance:

/** 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，类似这样：

So the code example is duplicated, not good. I want to use copydoc, something like this:

/** \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引用且本身不呈现任何内容的标记。但是，这只是我的想法，可能会有更好的想法。

This is actually as far as I have gotten, but I'm not satisfied with it since I don't know how to hide the dummy page 'ResourceExampleTag' I'm creating to copy from. So somewhere in the resulting documentation there's a page with some code completely out of context. As far as I can see the thing here is to find a tag which can be referenced by copydoc and which doesn't render any content on itself. However, that's just my line of thought, there might be far better ones.

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

I can also mention that I (for several reasons I won't bother to go into) don't wish to use the \example tag with external example code files.

谢谢。

推荐答案

我发现了@snippet命令对您尝试创建内联示例更有用。基本上我的示例都有一个源文件，my_examples.cpp

I've found the @snippet command to be more useful for creating examples inline like you are trying to do. Basically I have a source file for my examples, 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来使用示例。

Then in the doxygen documentation block for your function use @snippet to use the example.

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

...当然，只有在回答完之后，我才知道你不想使用外部文件，但是由于我偶然发现了尝试执行此处所述操作的问题，因此它可能对某人有用！

... And of course only after finishing the answer, do I realize you didn't want to use an external file, but since I stumbled upon the question trying to do what I described here, it might be useful to someone!

这篇关于Doxygen copydoc标签可重用代码示例的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！