Re: Ada documentation tools.

[Georg Bauhaus <rm.dash-bauhaus@futureapps.de>]

On 15.11.10 15:25, AdaMagica wrote:

> The original wish was to have something like JavaDoc for Ada, which
> just extracts the comments and strips the implementation to produce
> something similar to what the Ada spec is per se.
> 
> Colouring, fonts etc. are rather more than just JavaDoc (modern
> language sensitive IDEs have all this). OK, I haven't used Java for
> years, so perhaps JavaDoc today is more than then.

JavaDoc does more than to extract, literally.  JavaDoc is a small
tagging language.  The tags introduce references to items internal
and external to the Java source.  Internal references are checked.

Then, stale comments, referring to parameters that do no longer
exist are not possible. For example, when using the  @param tag
in the method comment.

Python, similarly, has a mechanism for associating comments
and definitions: documentation strings. These comments are
run-time entities, available to any program in the __doc__
attribute of any objects (this includes functions and classes
which are objects, too).

<Example>

Python>>> print str.__doc__
str(object) -> string

Return a nice string representation of the object.
If the argument is a string, the return value is the same object.
Python>>>

</Example>

Python users have established an informal convention about
identifier names in comments. Ada users haven't, have they?

The informal convention is to place identifier names between
`backticks` when the word refers to named variables of that name.

- Python has full introspective capabilities ...

- Algol 60 (!) has the "comment" key word.

- Eiffel has an "indexing" section at the start of each class.

The Ada language---it keeps being associated with software
engineering---must, to support this association, have supporting
tools that address proper comments.  And do it formally,
otherwise documentation is necessarily bricolage.