Custom tags with Doxygen

Question

I am trying to figure out if there is a way to create a custom tag using Doxygen. I did find the ALIAS configuration file option but that does not do exactly what I need. Basically in my code I want to be able to write something like

/// \req Requirement #322 - blah blah 

And then have Doxygen create a list like it does for \bug and \todo commands for lines that have this custom tag. Is this possible with Doxygen?

Answer 1

The generalization of \bug and \todo is \xrefitem.

The solution I suggest is:

• in Doxyfile:

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

• in documented code:

  /// \req #42 - The system shall work in any situation 

Answer 2

Thanks mouviciel! I have adopted your solution and extended it for my purposes.

The text below goes into my Doxyfile:

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

Where SRTX is the name of my project and is used as a prefix to requirements.

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/mantis/view.php?id=1113">SRTX-1113</a>  @anchor SRTX_1114 <a href="https://foo.bar.com/mantis/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).