Re: Ada documentation tools.

["Peter C. Chapin" <pcc482719@gmail.com>]

On 2010-11-15 07:38, AdaMagica wrote:

> Cross-referencing can best be done via the internal program
> representation (ASIS e.g.). Why is a browser to be preferred to an IDE
> like GPS?

It works better on web pages. Documentation in HTML format can be
presented on the web for reference or whatever. It could probably also
be converted into, for example, CHM format (not sure... haven't actually
tried it).

Doxygen can extract information from the source (not just comments, but
also semantic information from the code itself) and format it as RTF or
even LaTeX. There are situations where that is nice.

Actually another advantage of using such tools is that it "forces"
developers to use a standardized commenting style. For example if I have
to use a @param tag, or something similar, to introduce the
documentation for a parameter then I know that everyone on the project
will be introducing parameter documentation the same way. That's a nice
thing too. Comments are free formatted, which can be good at times, but
there are also times when I'd like to impose structure on them.

Speaking of Doxygen... one thing that I rather like about it is that it
allows you to include comments on either the declaration or the
definition of a function. The Ada tools I've seen so far believe that
all "documentation" comments should appear in the specification. I agree
that is logically where they should go but from a maintenance point of
view it can be nice to have the documentation for a subprogram right
where one spends time editing that subprogram. I understand this invites
confusion between documentation for users vs documentation for
implementers. Still, it's a nice option to have when used with caution.

> Would you try to
> browse through a HOOD design or UML model created with some tool with
> a browser instead of a dedicated tool?

I could imagine wanting to do that, yes.

Peter