I have a fair understanding of both how to document code and how to write "generic documentation" using @mainpage
, @page
, @subpage
and related tags.
I would need to include requirements/specification documentation for the code.
My problem is to keep this kind of documentation (conceptually distinct from code documentation) close to code implementing functionality (i.e.: at least in the same file, sometimes even near specific classes/functions/methods) but still be able to collect it in an orderly fashion and present it in the @mainpage
, outside file/class hierarchy.
What I would ideally need is to be able to place specific @page
, @section
, @subsection
etc. randomly in the various source files and then be able to @include
them in a specific order into @mainpage
or some other @subpage
.
Even better would be to be able to include the same snippet in both class/function full doc (not @brief
, of course) and in the "front matter" linked in @mainpage
.
Global effect I need to have is to have a "specification document" where I detail what the various parts of the code need to implement and then the "normal class/function/whatever" documentation doxygen id very good at providing.
The catch (i.e.: what I don't know how to do) is I would like to keep "specification" and implementation together in the source, but separate them in documentation, i.e.:
@mainpage
@mainpage
.Is this possible?
If so, what's the best practice?
Note: I could get the effect using a separate file for each "doc snippet" and then @include
ing it in the right places, but that would defeat the whole purpose that's keep Requirements/Specification/code together while separating them in different sections in the resulting documentation.
Update: following @albert comment I tried the following:
/**
* Initialization function.
*
* [AM_init]
* It needs to do a long series of tests to ensure AM can actually work.
*
* It should also allocate all dynamic memory needed to avoid runtime failures.
*
...
* It will be responsibility of system-level daemon to take appropriate action.
* [AM_init]
*
*
* @param ip_addr
* @param port
* @return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port) {
...
/**
@page __init Initialization
@snippet{doc} CommandHandler.c AM_init
*/
Initialization
It needs to do a long series of tests to ensure AM can actually work.
that's it.
Apparently the tag is found, but only the first line is actually included.
Further Update: Following @albert answer (accepted) I had success, but the following caveats:
[AM_init]
) must be in a standard comment, not a doxygen one, otherwise snippet ends up included twice.*
(very common in "standard comments".<br/>
for line termination) because Markdown constructs ("double newline", in the above case) are notrecognized.In retrospect I think "Note" in Doxygen \snippet['{'option'}'] <file-name> ( block_id )
documentation addresses, more or less all the above, but I find it very cryptic and I would never have understood the implications without my nose being rubbed into them.
The last one is very annoying because I use a lot Lists and Tables and while HTML syntax is much more powerful, it is also much more difficult to write and to read in sources.
Finding a way to lift this limitation would be "very nice".
With the following code and the current doxygen version (1.9.4 (5d15657a55555e6181a7830a5c723af75e7577e2)) but also with the 1.9.1 (ef9b20ac7f8a8621fcfc299f8bd0b80422390f4b) version, I get good result:
bb.h
/// \file
/**
@page __init Initialization
@snippet{doc} CommandHandler.c AM_init
*/
CommandHandler.c
/// \file
/**
* Initialization function.
*/
/* [AM_init]
It needs to do a long series of tests to ensure AM can actually work.<br>
It should also allocate all dynamic memory needed to avoid runtime failures.<br>
It will be responsibility of system-level daemon to take appropriate action.<br>
[AM_init]
*/
/**
* \snippet{doc} this AM_init
*
* @param ip_addr
* @param port
* @return
*/
static uint32_t AM_init(const char* ip_addr, uint16_t port){}
Doxyfile
EXTRACT_STATIC = YES
EXAMPLE_PATH = .
QUIET = YES
Note: OP rightfully mentioned in further update that there are some things to take care of: