Doxygen copydoc tag для повторного использования примеров кода - PullRequest
Новая
       2

Doxygen copydoc tag для повторного использования примеров кода

6 голосов
/ 15 февраля 2011

Я хочу повторно использовать блок примера кода, используя тег \ 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, и который не отображает сам по себе контент.Тем не менее, это всего лишь моя точка зрения, возможно, есть и лучшие.

Я также могу упомянуть, что я (по нескольким причинам не буду вдаваться в подробности) не хочу использовать \ примертег с внешними примерами кодовых файлов.

Спасибо.

Ответы [ 3 ]

11 голосов
/ 07 февраля 2012

Это работает для меня: 

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 должна быть пустая строка, иначе она не работает (иногда, не всегда ...)

5 голосов
/ 08 декабря 2013

Я обнаружил, что команда @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 );

..И, конечно, только после завершения ответа я понимаю, что вы не хотите использовать внешний файл, но, поскольку я наткнулся на вопрос, пытаясь сделать то, что я здесь описал, он может быть кому-то полезен!

0 голосов
/ 24 июня 2011

У меня была та же проблема, и я не смог найти элегантного решения.В конце концов мне пришло в голову следующее:

1) На какой-то случайной странице ссылка на новую подстраницу с именем Hidden 

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

2) Создать скрытую страницу, ссылающуюся на вашу «пустышку»пример темы.Назовите страницу &nbsp;

/*! \page Hidden &nbsp;
    \subpage MyExample
   */

3) Теперь вы можете \copydoc MyExample где угодно, и она невидима для пользователей HTML, генерируемого doxygen.

...