CODEWITHSUNDEEP
markdowndoxygen
BobMorane
BobMorane

Reputation: 4306

How to include sources in Doxygen/Markdown

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.

Upvotes: 0

Views: 121

Answers (2)

albert
albert

Reputation: 9077

Based on the answer https://stackoverflow.com/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):

enter image description here

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:

enter image description here

When looking at the markdown file:

Just a page
===========

Lets include some text
\snippet source.c mytag

which looks in doxygen like:

enter image description here

which looks e.g on GitHub like:

enter image description here

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:

enter image description here

Upvotes: 1

Thor-x86_128
Thor-x86_128

Reputation: 361

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?

Upvotes: 1

Related Questions