Re: [Doxygen-users] adding doxygen comments to code

[Ron W <ron...@gm...>]

On Mon, Jun 29, 2015 at 4:32 PM, woody <kn...@re...> wrote:

> The html documentation has the line numbers, as does the rtf file, so
> obviously it is tracking at some level.
>
> I see that the call graphs are interspersed through the rtf file, but they
> are not really grouped into a coherent structure.
> And I never found them at all in the html generated stuff.
>
>
> *::#define CONTROL_TABLE 1 *Definition at line 388 of file
> medbest_310_o_split.c.
>
> *::void adc_window_complete ()*


I meant for the references. I know it records the line numbers of the
definitions.


>
> There is the @brief and a ton more.
>

We use "AUTO_BRIEF" in our Doxygen configuration so we rarely need @brief
or @details. Besides @return, we use @f$, @f[ and @f] (for formulae),
@note, @internal/@endinternal, @ref, @see, @page, @section, @test, @todo,
and a few custom directives.* But, most of the time, we only need
descriptive prose.

> I don't know what requirements IEC 62304 imposes, particularly on "in
> line" code documentation.
>
>
> It is a very long discussion
>

Looks very similar to ISO-26262. Doxygen helps us here because we can
define the interfaces directly at the code level and generate an interface
document from that. Otherwise, Doxygen's strength is in generating low
level documentation. Higher level documentation, we use Dia to create
diagrams and charts and Libre Office to write prose.

* Our custom Doxygen directives include @req (for denoting requirements (by
ReqID)), @range (for annotating limits and constraints) and @issue (for
annotating code changes made per issue tracking).