45

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?

Chris
  • 44,602
  • 16
  • 137
  • 156
RishiD
  • 2,098
  • 2
  • 26
  • 24

3 Answers3

53

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
mouviciel
  • 66,855
  • 13
  • 106
  • 140
28

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

Daniel
  • 3,243
  • 2
  • 32
  • 31
  • Add the `Requirements.dox` specified above in the `INPUT=` variable to be able to see the links, in the "Requirement Implementation" and "Requirement Verification" pages. – parasrish Nov 08 '17 at 10:27
  • is it also possible to add a reverse lookup, in order to see the list of req and which function implements/versify it ? – phschoen Sep 14 '21 at 15:18
6

Combining the two answers above, you can have a single clean requirement tag that will build a cross-reference table, and, also provide a direct link to the requirement repo in your docs:

Doxygen CONFIG file:

ALIASES = "requirement{1}=@xrefitem requirement \"Requirements\" \"Requirements Traceability\" <a href=\"http://your.requirementtool.com/browse/\1\">\1</a>"

Source code:

@requirement{REQ-123} Brief textual summary of this requirement item

This will render in the documentation as:

Requirements:

  • REQ-123 Brief textual summary of this requirement item
Jay
  • 61
  • 1
  • 3
  • Nice answer - off topic, what open source requirement traceability tool do you recommend to be used in this situation? – Mircea Ionica Mar 11 '19 at 07:18
  • A little off topic? ;) I've used a _lot_ of commercial requirements tools. Requirements for JIRA (R4J) provides the best integration (to s/w teams using JIRA) and lightweight usability for small - medium s/ware projects, imho. I've not evaluated open-source alternatives seriously. ReqIF was an industry-standard requirements interchange format - take a look at the tools that support that. Most requirements tools suffer the same problem: they are an _information island_ - with poor integration to your existing tools and processes - try to find something that works with your toolchains. – Jay Mar 12 '19 at 21:41
  • Hi @Jay, in this way I get the relationship between the functions that satisfy a requirement and a requirement, obtaining a section in which there are listed all the functions and for each of them the requirements they satisfy. Is there a way to get the inverse matrix of the relationship? Obtaining another section in which all the requirements are listed indicating the functions that satisfy each requirement. – s_frix May 06 '22 at 10:07