Расширенная документация модуля/группы во внешнем файле

Question

У меня может быть простая проблема, но мой Google-Fu не дал никаких результатов.

У меня есть Doxygen документированы файл заголовка, как это:

/** 
* @file filename.h 
* 
* @date today 
* @author me 
* 
* @defgroup mygroup grouptitle 
* @brief my nice functions 
* 
* Here is a medium sized description, 4-5 lines, which outline the 
* functions and the way these functions work together, what is init, 
* what is the main function of this module and maybe additional 
* information on used hardware (as it is mainly embedded software). 
* 
* Here starts another description block, typical length around 20-50 
* lines. Detailed Hardware description, code snippets as examples and 
* so on. I want to remove this section from the header file and 
* replace it by something like 
* /special_doyxgen_command_to_insert extended_doc_mygroup.md 
* 
* \addtogroup mygroup 
* @{ 
*/ 

here are function definitions, enums, defines and what else 

/** @} */ 

Я понятия не имею, если это возможно, но у меня есть дополнительный mygroup.md, в котором приведены некоторые примеры и и общее использование показано , В зависимости от файла он имеет 10-50 строк, в основном 1 или 2 примера кода.

В прошлом я вставлял примеры в файл header/source, но мне не нравится этот подход, поэтому я создал файл разметки и связался с ним с помощью функций doxygen ref. Я хотел бы отметить тег «insert», который вставляет .md contend в разделе «Подробное описание» моей групповой документации (файлы HTML и Latex).

Есть ли такая команда (или набор команд, чтобы получить мой подход?)

Answer 1

Есть много команд существующих включать внешние примеры кода в документации. Посмотрите на тег конфигурации EXAMPLE_PATH и специальные команды @include и @snippet. Вы можете создать каталог под названием «примеры», где вы положили ваши файлы примеров в и скажите Doxygen, введя этот каталог в EXAMPLE_PATH тег:

EXAMPLE_PATH = ./examples 

Затем вы создаете несколько примеров файлов, например: examples_1.c

/// [Example1] 
/// Here some more text to explain the example which is not shown by the \@snippet command. 

// But normal comments are shown as a part of the code 
for(;;) 
{ 
    doSomething(); 
} 
/// [Example1] 

/// [Example2] 
while(1) 
{ 
    doSomething2(); 
} 
/// [Example2] 

Теперь вы можете добавить эти фрагменты кода с помощью команды @snippet в вашей группе документации:

/** 
* @defgroup ... 
* ... 
* @snippet examples_1.c Example1 
* ... 
* @snippet examples_1.c Example2 
*/ 

в качестве альтернативы вы с включаемый код целого исходного файла:

/** 
* ... 
* @include examples_2.c 
* ... 
*/ 

Другой aprroach вы должны смотреть на это использование команды @copydoc и @copydetails.

Надеюсь, это ответит на ваш вопрос.