When documenting with Doxygen, one can add additional documentation through .dox, text or Markdown files.
In a project, I am using Markdown files to add extra documentation and really like it. There is one case, however, where I can’t seem to be able to do everything .dox file can. If I want to include some snippet of code from a source file as a code block. Using .dox files, I would simply write:
include main.cpp
to have the content of main.cpp included verbatim as a code block in the resulting documentation.
In Markdown, all I have seen are code blocks embedded directly in the Markdown source through the “` notation.
Is there a way, using Doxygen with Markdown, to include code from sources files in the documentation?
I am using doxygen 1.10.0.
2
This example is work for me. Let’s say there is a “source.c” and need to be included into “destination.md”.
source.c
//! [Your tag name here]
int foodler(int input) {
return input - 1;
}
//! [Your tag name here]
Notice that there are [Your tag name here]. Any code that lives between those comment lines will be considered as a snippet, named “Your tag name here”. Then, to use the snippet:
destination.md
Hello folks! this is my code:
snippet path/to/source.c Your tag name here
Cool, isn't it?
2
Based on the answer /a/78942289/1657886and the comments with the original question How to include sources in Doxygen/Markdown some further explanation (all shown with the current 1.12.0 doxygen version).
When having in the source.c:
//! brief some brief text
//! [mytag]
int foodler(int input) {
return input - 1;
}
//! [mytag]
this will result in the resulting documentation of the function foodler (provided you also want to show the content of source.c which normally would be the case as a snippet points often to some real code of the project):
note the [mytag].
This problem can be overcome by using noop (see: https://www.doxygen.nl/manual/commands.html#cmdnoop):
//! brief some brief text
//! noop [mytag]
int foodler(int input) {
return input - 1;
}
//! noop [mytag]
which results in:
When looking at the markdown file:
Just a page
===========
Lets include some text
snippet source.c mytag
which looks in doxygen like:
which looks e.g on GitHub like:
Note the snippet line.
This can be overcome by using <!--! ... --> (see the end of the paragraph https://www.doxygen.nl/manual/htmlcmds.html#htmltagcmds):
Just a page
===========
Lets include some text
<!--! snippet source.c mytag -->
which with doxygen doesn’t make a difference but with GitHub gives: