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.
_______________________________________________
devel mailing list
devel@rtems.org
http://lists.rtems.org/mailman/listinfo/devel
