问题
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 );
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 );
I.e. code example in one place, reused in other places.
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.
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.
Thanks.
回答1:
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]
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!
回答2:
This works for me:
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();
};
and then in the doxygen configuration you set EXCLUDE_SYMBOLS = hide_*
The the documentation is copied from the hide_commonstuff
but this class is not shown in the class list.
Also: there needs to be a blank line before @copydoc
or else it does not work (sometimes, not always...)
回答3:
I had the same issue and couldn't find any elegant solution either. I eventually came up with the following:
1) On some random page, link to a new subpage called Hidden
/*! \mainpage My MainPage
blah blah blah
\subpage Hidden
*/
2) Create the hidden page, linking to your 'dummy' example topics. Name the page
/*! \page Hidden
\subpage MyExample
*/
3) Now you can \copydoc MyExample
wherever you like, and it is invisible to users of the HTML generated by doxygen.
来源:https://stackoverflow.com/questions/5002827/doxygen-copydoc-tag-to-reuse-code-examples