Traceability from specification to source code?

[Sebastian Huber]

Hello Joel,

thanks for your comment.

On 17/04/2020 16:41, Joel Sherrill wrote:
> Code annotations are a must. Sebastian is right that putting something
> above the body is the way to go. We are using a requirements comment
> block above the entry point to the method. A script integrates with the
> commercial tool. They analyse the source and provide file, line number,
> and signature (e.g. tags). From that, you can easily find those special
> comments with requirements. You do have to address the case where
> there are no requirements or an incorrectly formatted set. But that's
> the practical matter of what you have to do.
>
> If you put in a bad requirement tag, then it will just show up as an
> error when you process and some requirement will be uncovered
> in the traceability report.
>
> There are a lot of details to work out. Doxygen is slow. Would ctags
> or something similar be faster?

Since code annotations were not welcome I searched for an alternative 
solution. I first had ctags in mind. Universal ctags has the ability to 
produce JSON output:

https://github.com/universal-ctags/ctags

The problem is now how to teach Doxygen the links back to the 
specification (without annotations in the source files)? What seems to 
work is adding a generated file which contains stuff like this:

/**
  * @fn RTEMS_INLINE_ROUTINE uint64_t _Watchdog_Ticks_from_seconds 
(uint32_t seconds)
  *
  * bla blub
  */

For this you need the function signature in a way so that Doxygen is 
able to find the corresponding part in the sources and add the generated 
content. The problem is that ctags doesn't deliver this (at least I 
don't know how). This is how I ended up using the tagfile.

You say that code annotations are a must. Do you think that there exist 
some items in the code which require traceability to the specification 
and cannot be found by Doxygen?