I was trying to figure out how to integrate custom tags in Doxygen. It came to me while I was documenting my code, and got the idea of having the requirements listed in the automated documentation of the code. My idea is to link some code block to requirements. My first approach would be to right the following comment to add it in a list, like \bug and \todo:

/// \req #322 - This is a requirement

In the Doxyfile, I need to add an Alias to create a custom command. The generalisation of \bug and \todo is \xrefitem. It would give something like this:

ALIASES += "req=\xrefitem req \"Requirement\" \"Requirements\" "

Now let’s say I want to connect my requirements to the “official” one stored in Jira or any websites. 

ALIASES += req{2}="\ref \1_\2 \"\1-\2\" "
ALIASES += satisfy{1}="\xrefitem satisfy \"Satisfies requirement\" \"Requirement Implementation\" \1"
ALIASES += verify{1}="\xrefitem verify \"Verifies requirement\" \"Requirement Verification\" \1"

Where 1 is the name of my project and is used as a prefix to requirements. And \2 is the requirement code.

Then I create a file called Requirements.dox that provides a link between the requirement id and a URL for the requirement in my requirements management tool (an issue tracker in my case).

/**
@page Requirements

@section Build1

@anchor SRTX_1113
<a href="https://foo.bar.com/jira/view.php?id=1113">SRTX-1113</a>

@anchor SRTX_1114
<a href="https://foo.bar.com/jira/view.php?id=1114">SRTX-1114</a>

*/

One could also put the text of the requirement in the anchor tag if you didn’t need to link to an external source.

In my code I have:

/**
 * This is the basic executive that schedules processes.
 * @satisfy{@req{1114}}
 */
class Scheduler: public Process
{
    ...
}

And in my tests I put:

/**
 * Provide a number of tests for process scheduling.
 * @verify{@req{1114}}
 */
class Scheduler_ut : public CppUnit::TestFixture
{
    ...
}

This gives me related pages for Requirements, Requirements Implementation, and Requirements Verification. It also provides Satisfies requirement and Verifies requirements sections in the class description (or function — wherever you put the tag).

To add the Requirements.dox, I specify it in the INPUT= variable to be able to see the links, in the “Requirement Implementation” and “Requirement Verification” pages.

A useful reminder:

While it is not as clean as @param, you can emulate similar behavior with the following aliases:

ALIASES += options="<dl class="params"><dt>Options</dt><dd><table class="params">"
ALIASES += option{2}="<tr><td class="paramname">\1</td><td>\2</td></tr>"
ALIASES += endoptions="</table></dd></dl>"

The aliases can be used as follows to produce the output you’re looking for:

/**
 * @options
 * @option{ option_1, This is the first option. }
 * @option{ option_2, This is the second option. }
 * @endoptions
 */

Note: This is HTML-centric and likely will not produce reasonable output for other formats.