Traceability from specification to source code?

[Sebastian Huber]

Hello,

with the pre-qualified build of RTEMS

https://lists.rtems.org/pipermail/devel/2020-April/059445.html

I try out the following approach. I run Doxygen on the set of 
pre-qualified files to produce the documentation and a tagfile:

# The TAGFILES tag can be used to specify one or more tag files. For 
each tag
# file the location of the external documentation should be added. The 
format of
# a tag file without this location is as follows:
# TAGFILES = file1 file2 ...
# Adding location for the tag files is done as follows:
# TAGFILES = file1=loc1 "file2 = loc2" ...
# where loc1 and loc2 can be relative or absolute paths or URLs. See the
# section "Linking to external documentation" for more information about 
the use
# of tag files.
# Note: Each tag file must have a unique name (where the name does NOT 
include
# the path). If a tag file is not located in the directory in which 
doxygen is
# run, you must also specify the path to the tagfile here.

The tagfile is in XML and contains things like this:

     <member kind="function">
       <type>RTEMS_INLINE_ROUTINE uint64_t</type>
       <name>_Watchdog_Ticks_from_seconds</name>
<anchorfile>group__RTEMSScoreWatchdog.html</anchorfile>
<anchor>gae368bd39a2a612b0e7701d954d363ce6</anchor>
       <arglist>(uint32_t seconds)</arglist>
     </member>

In the specification, I place a reference like this:

ref:
- kind: function
   name: _Watchdog_Ticks_from_seconds

I can then use the tagfile to lookup this reference. With the 
information in the tagfile, I can generate additional documentation 
content, for example:

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

In a second Doxygen run, this information is added to the 
_Watchdog_Ticks_from_seconds() documentation:

Converts the seconds to ticks.

Parameters
     seconds    The seconds to convert to ticks.

Returns
     seconds converted to ticks.

bla blub

The benefits of this approach is that we don't have to modify the RTEMS 
sources for the specification traceability and the references in the 
specification can be done at a high level without a lot of details.