Re: Q: Generating Documenation from Ada Sources?

[Stephen Leake <stephen.a.leake.1@gsfc.nasa.gov>]

Michael Erdmann <Michael.Erdmann@snafu.de> writes:

> Dr. Michael Paus wrote:
> > It sounds as if you are looking for something like JavaDoc (for Ada).
> > Hava you tried AdaBrowse?
> > (http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/)
> > I have not had the time to try it out but it is supposed to do what
> > you want.
> >
> Thanks i have tried it. What i am interested is more centered on
> processing text in the source. Your browser does not care about
> the contents of the comments. It is left to the used to build in
> tags or not.

AdaBrowse is Open Source, so you can enhance it. Surely an ASIS-based
tool is the right way to go for an Ada documentation project :). At
least, if you need to go beyond cat (I agree with Robert Dewar here;
just write good comments!).

> What i am looking for i a tool which maps the relevant part of the
> coments in a package spec. and transforms this into a docbook
> document. 

This should be easy to add to AdaBrowse. You do have to establish
conventions in coding style, so AdaBrowse+ can know which comments are
"relevant".

> In order to do so such a program requieres certain key words.
> Theretically the comment in the source could already contain docbook
> format but i dont like the idea, since the comments are getting
> unreadable. I gues what i am looking for i a tool which is abble to
> retrieve sections identified by headlines from normal and to convert
> it into docbook format. Copying in the specification of a procedure
> is the minor part of it.

Ok, you want a somewhat elaborate syntax in the comments. AdaBrowse at
least gets you the top level source traversal, and lets you write the
comment parsing in Ada. Use GNAT.Spitbol or GNAT.Regexp, or
Ada.Strings.Fixed, or OpenToken.

> Any way, adabrowser is based on asis, which requieres that the
> module is compilable which i cannot gurantee.

Why not? Surely you want to know that the document is accurate, which
means that the Ada code compiles! Otherwise you could have
inconsistent information!

Sometimes in reverse engineering an application, the code does not yet
compile because you have switched compilers or OSs or something. But
in that case, I don't see how this sort of documentation can help;
it's really just a prettier form of the source. If you were attempting
to create top-level withing charts or data flows, then being able to
process non-compilable code might be relevant.

-- 
-- Stephe