Doxygen copydoc tag to reuse code samples

Question

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

Explain the problem. Say I have two documented functions:

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

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

In many cases, I want to give a small code example on how to use a function in context, which is often associated with the use of a number of functions that can all be adequately represented by the same code example, for example:

/** 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 sample code 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 );

those. sample code in one place, reused in other places.

, , , , ResourceExampleTag, . , - , . , , copydoc, - . , , .

, ( , ) \example .

.

Answer 1

@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 2

:

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 3

, . :

1) On some random page, a link to a new subpage called Hidden

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

2) Create a hidden page by linking to your 'dummy' topics. Name the page 

/*! \page Hidden  
    \subpage MyExample
   */

3) Now you can \copydoc MyExamplewherever you want, and it is invisible to HTML users created by doxygen.