Как включить исходники в Doxygen/Markdown
При документировании с помощью Doxygen можно добавить дополнительную документацию через .dox, текстовые файлы или файлы Markdown.
В проекте я использую файлы Markdown для добавления дополнительной документации, и мне это очень нравится. Однако есть один случай, когда я не могу сделать все, что может .dox файл. Если я хочу \включить некоторый фрагмент кода из исходного файла в качестве блока кода. Используя файлы .dox, я бы просто написал:
\include main.cpp
чтобы содержимое main.cpp было включено дословно в качестве блока кода в результирующую документацию.
В Markdown все, что я видел, — это блоки кода, встроенные непосредственно в исходный код Markdown через нотацию ```.
Есть ли способ, используя Doxygen с Markdown, включить в документацию код из исходных файлов?
Я использую doxygen 1.10.0.
@albert, пожалуйста, дополни мой ответ твоим, чтобы мы могли понять, что ты пытаешься объяснить.
Ответы 2
Этот пример для меня работа. Допустим, есть «source.c», и его нужно включить в «destination.md».
source.c
//! [Your tag name here]
int foodler(int input) {
return input - 1;
}
//! [Your tag name here]
Обратите внимание, что есть [Your tag name here]. Любой код, который находится между этими строками комментариев, будет рассматриваться как фрагмент с именем «Здесь ваше имя тега». Затем, чтобы использовать фрагмент:
destination.md
Hello folks! this is my code:
\snippet path/to/source.c Your tag name here
Cool, isn't it?
См. также мой комментарий с вопросом.
Я не знал, что мы можем использовать специальные команды Doxygen непосредственно в Markdown.
На основе ответа https://stackoverflow.com/a/78942289/1657886 и комментариев с исходным вопросом Как включить источники в Doxygen/Markdown некоторых дополнительных объяснений (все показано с текущей версией 1.12.0 doxygen версия).
Когда в source.c:
//! \brief some brief text
//! [mytag]
int foodler(int input) {
return input - 1;
}
//! [mytag]
в результате вы получите результирующую документацию функции foodler (при условии, что вы также хотите показать содержимое source.c, что обычно имеет место, поскольку фрагмент часто указывает на какой-то реальный код проекта):
обратите внимание на [mytag].
Эту проблему можно решить, используя \noop (см.: https://www.doxygen.nl/manual/commands.html#cmdnoop):
//! \brief some brief text
//! \noop [mytag]
int foodler(int input) {
return input - 1;
}
//! \noop [mytag]
что приводит к:
При просмотре файла уценки:
Just a page
===========
Lets include some text
\snippet source.c mytag
который выглядит в doxygen так:
который выглядит, например, на GitHub так:
Обратите внимание на строку \snippet.
Это можно преодолеть, используя <!--! ... --> (см. конец абзаца https://www.doxygen.nl/manual/htmlcmds.html#htmltagcmds):
Just a page
===========
Lets include some text
<!--! \snippet source.c mytag -->
что с doxygen не имеет значения, но с GitHub дает:
Какую версию doxygen вы используете? Ответ от @ Thor-x86_128 правильный, но я бы также рассмотрел возможность добавить
\noopперед частью[...], чтобы[...]не отображался в документации (в данном случае командыfoodler. Rge\include/\snippetне являются собственными командами уценки). но возможности doxygen, вам также следует взглянуть на<!--!... -->(см. doxygen.nl/manual/htmlcmds.html#htmltagcmds), который добавлен в версию doxygen 1.12.0.