Doxygen: как добавить страницу уценки для документирования группы

Question

У меня довольно сложный проект, и я хочу документировать его с помощью doxygen.

У меня нет проблем с документированием кода, и мне также удалось создать красивую титульную страницу, используя пользовательский файл README.md в сочетании с директивой "USE_MDFILE_AS_MAINPAGE = README.md" в Doxyfile.

Я определил несколько групп (@defgroup), которые отображаются в моей документации как "Модули".

Я хотел бы добавить "главную страницу" к каждой группе, предоставляющей общую информацию, помимо документации по обычной функции / переменной / типу.

Я попытался добавить пользовательские MODULENAME.md файлы в сочетании с соответствующими @includedoc MODULENAME.md записями в определении группы, похоже, это работает (я вижу несколько строк вроде: "Generating docs for page md_mcu_noitr_coro_README..."), но я не могу найти, если и где находится страница связанный (я ожидал увидеть его в «Подробном описании» для модуля, как это происходит, если я помещаю некоторую документацию в строку, где я помещаю директиву «@includedoc».

фрагмент одного из моих модулей:

/**
 * @file coro.h
 * @brief definition of coroutine implementing functions.
 *
 * @date: Feb 8, 2018
 * @author: myself
 *
 * @defgroup coro "Coroutine implementation in plain 'C'."
 *
 * @includedoc mcu_noitr/coro/README.md
 * @{
 *
 */

Что я делаю не так?

Примечание: также немного удивительно, что мне нужно указать весь путь от моего Doxyfile, иначе doxygen не найдет его, даже если он находится рядом с файлом, содержащим @includedoc команда.

Answer 1

Я также столкнулся с проблемой, заключающейся в том, что включенные файлы с форматированным текстом Markdown через \includedoc или \include{doc} не приводят к правильно интерпретированной Markdown. Обратите внимание, что я включил файлы Markdown из других файлов Markdown. Мой обходной путь состоял в том, чтобы использовать препроцессор C (cpp) - который широко доступен - в файлах Markdown и использовать его директиву #include. Конечно, вы можете использовать настоящий общий текстовый процессор, такой как M4 , как предложено на странице руководства cpp. Установите FILTER_PATTERNS в Doxyfile как:

FILTER_PATTERNS = *.md="cpp -P -traditional-cpp"

Вам понадобится опция -P, чтобы избежать вывода строковых маркеров, что сбивает с толку Doxygen. -traditional-cpp было необходимо для того, чтобы cpp не использовал пустое пространство, что важно для правильной интерпретации уценки. Не используйте одинарные кавычки, так как это приводит к ошибке, когда Doxygen вызывает cpp через sh.

Тогда на моей главной странице Markdown:

Main Page {#mainpage}
==========

Blah blah blah.

#include "other.md"

Использование FILTER_PATTERNS вместо INPUT_FILTER позволяет избежать проблемы, связанной с невозможностью добавлять или удалять строки.

У меня есть файлы разметки в одном и том же каталоге, и я думаю, что, если они находятся в разных местах, вы можете сообщить об этом cpp через -I, что позволит удовлетворить ваши ожидания относительно путей включения в вопросе вы подали.

Answer 2

В настоящий момент doxygen не учитывает тот факт, что такие команды, как \includedoc, могут содержать код уценки. На данный момент единственной возможностью будет написать фильтр, см. Параметр конфигурации INPUT_FILTER в файле конфигурации doxygen (не проверено!), Чтобы заменить \ includeoc` кодом этого файла.