Extended Module/Group Documentation in external file - c

Question

I have a maybe simple problem, but my Google-Fu produced no results.
I have a doxygen documented header file like this:
/**
* #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
/** #} */
I have no idea if this is possible but I have an additional mygroup.md in which some examples are given and and the general usage is shown. Depending on the file it has 10 - 50 lines, mostly 1 or 2 code examples.
In the past I inserted the examples in the header/sourcefiles, but I don't like that approach, so I created a markdown file and linked to this via the doxygen ref functions.
What I would like is a 'insert' tag that inserts the .md contend in the 'Detailed Description' Section of my Group Documentation (the HTML and Latex files).
Is there such a command (or a set of commands to get my approach?)

Answer 1

There are many commands existing to include external code examples in your documentation. Have a look at configuration tag EXAMPLE_PATH and the special commands #include and #snippet. You could create a directory called "examples" where you put your example files into and tell doxygen by entering this directory in the EXAMPLE_PATH tag:
EXAMPLE_PATH = ./examples
Then you create some example files, e.g: 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]
Now you can add these code snippets using the #snippet command in your group documentation:
/**
* #defgroup ...
* ...
* #snippet examples_1.c Example1
* ...
* #snippet examples_1.c Example2
*/
Alternatively you can include the code of a whole source file:
/**
* ...
* #include examples_2.c
* ...
*/
Another aprroach you should look at is the usage of the #copydoc and #copydetails command.
Hope this answers your question.