Re: Q: Generating Documenation from Ada Sources?

[Michael Erdmann <Michael.Erdmann@snafu.de>]

Stephen Leake wrote:
> 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".
Actually this is what i am interested in. I like to avoid that
the user has to think about special tags and so on. I am
currently playing around with certain heutistics based on a
minimal common sense snytax, e.g.

Description
===========

....textblock ...


Means, the text block is a description, or e.g.

...listed below:

   * Item 1.....
   * Item 2 .....

is a list, where a list is always introduced by the ':' at the end
of a line and so on.


The input format should be a "normal" as possible in order to
avoid costly reformatting of older source parts.



> 
> 
>>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!
> 
May be you are right about this point. I think i will first
play with the heuristics above, then think about integrating
it into a tool like ada browser.

> 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.
> 
I am not focussing on reverese engeneering. I like to have a cheap
way of extracting the "important" parts of library components into
docbook documentation.

Regards
    M.Erdmann