doxygenspecificationsrequirements

How to generate "global documentation" with doxygen


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.:

  1. General Description: easy, this goes into @mainpage
  2. Requirements: most likely at top of source file implementing them, how do I link/include in main page?
  3. Specification: either right after Requirements at top of file or somewhere near class/function implementing it; also here I don't know how to link/include in "front matter" AKA: @mainpage.
  4. Normal code documentation: here only thing I don't know is how include in class/function description the same "doc snippet" already used for (2) and (3).

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 @includeing 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:

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".


Solution

  • 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: