Ada documentation tools.

Ada documentation tools.

[Peter C. Chapin]

Hello!

I'm looking for a tool that can extract nicely formatted documentation
from Ada sources + comments. I'm looking for something that is similar
in nature to Doxygen or Javadoc. It should be free and it should work on
Windows. I'm aware of AdaDoc, AdaBrowse, and the documentation generator
available in GPS. I'm wondering if there are any others I should be
looking at or if people have any feelings about which of these various
choices is "best."

Thanks,
Peter

Re: Ada documentation tools.

[AdaMagica]

Hm, I'm perhaps going to stir up a hornets' nest.

I really cannot understand why anyone would like something like
JavaDoc for Ada code. Java lacks separation of spec and body, thus
JavaDoc is a kludge.

The Ada spec, if written properly, is already the documentation - and
if it isn't, such a tool cannot cure the situation.

I've read (not such a lot) of Ada code documented in this style and
always found that I prefer the Ada spec directly.

So what do you expect from such a tool that the Ada spec does not yet
provide?

Re: Ada documentation tools.

[Maciej Sobczak]

On 14 Lis, 23:26, "Peter C. Chapin" <pcc482...@gmail.com> wrote:

> I'm looking for a tool that can extract nicely formatted documentation
> from Ada sources + comments. I'm looking for something that is similar
> in nature to Doxygen or Javadoc. It should be free and it should work on
> Windows. I'm aware of AdaDoc, AdaBrowse, and the documentation generator
> available in GPS. I'm wondering if there are any others I should be
> looking at

With a risk of shameless plug, I will kindly point you to the online
docs for YAMI4:

http://www.inspirel.com/yami4/doc/ada/

These pages were generated directly from *.ads files by a very simple
Tcl script that I have written explicitly for this purpose. I was not
satisfied with the visual presentation style offered by other tools.

The interesting thing about this script is that contrary to other
tools, it does not perform any sophisticated analysis of the spec
source - it only follows some simple text formatting patterns like
indentation and vertical whitespace. On one hand you can consider this
to be a severe limitation, but on the other hand this can be a
motivation to actually format the source code properly. It works well
for me.

The script is not published anywhere, but I will share it with anybody
who needs it, just contact me off the list.

--
Maciej Sobczak * http://www.inspirel.com

Re: Ada documentation tools.

[Maciej Sobczak]

On 15 Lis, 09:14, AdaMagica <christoph.gr...@eurocopter.com> wrote:

> So what do you expect from such a tool that the Ada spec does not yet
> provide?

Formatting. Presentation is not only about content.

--
Maciej Sobczak * http://www.inspirel.com

Re: Ada documentation tools.

[Georg Bauhaus]

On 15.11.10 09:14, AdaMagica wrote:

> So what do you expect from such a tool that the Ada spec does not yet
> provide?

I'd want source code navigation in comments.

Navigating to relevant documents from within the IDE
is also convenient.

Assume a standardized tagging syntax for comments
(cf. SPARK).  Then tools can more easily turn Ada
specifications into hypertext (needs *not* be HTML,
and needs not force us out of the IDE).

Re: Ada documentation tools.

[Peter C. Chapin]

On 2010-11-15 03:14, AdaMagica wrote:

> So what do you expect from such a tool that the Ada spec does not yet
> provide?

Mainly I want cross-referenced documentation that is easy to browse. I
realize that IDEs can provide much of this support but I like having
documentation that can be read without the help of a specific IDE (for
example, in any web browser).

Peter

Re: Ada documentation tools.

[AdaMagica]

On 15 Nov., 10:49, Maciej Sobczak <see.my.homep...@gmail.com> wrote:
> On 15 Lis, 09:14, AdaMagica <christoph.gr...@eurocopter.com> wrote:
>
> > So what do you expect from such a tool that the Ada spec does not yet
> > provide?
>
> Formatting. Presentation is not only about content.

Hm. How can a tool improve bad formatting in the code? Format the code
correctly in the first place.

Re: Ada documentation tools.

[AdaMagica]

On 15 Nov., 12:40, "Peter C. Chapin" <pcc482...@gmail.com> wrote:
> On 2010-11-15 03:14, AdaMagica wrote:
>
> > So what do you expect from such a tool that the Ada spec does not yet
> > provide?
>
> Mainly I want cross-referenced documentation that is easy to browse. I
> realize that IDEs can provide much of this support but I like having
> documentation that can be read without the help of a specific IDE (for
> example, in any web browser).
>
> Peter

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? OK, you can use it without a compiler being present. This
seems like a weak reason. Modern software needs the appropriate tools
to read, and for source code, this is the compiler. Would you try to
browse through a HOOD design or UML model created with some tool with
a browser instead of a dedicated tool?

Re: Ada documentation tools.

[Niklas Holsti]

Peter C. Chapin wrote:
> On 2010-11-15 03:14, AdaMagica wrote:
> 
>> So what do you expect from such a tool that the Ada spec does not yet
>> provide?
> 
> Mainly I want cross-referenced documentation that is easy to browse. I
> realize that IDEs can provide much of this support but I like having
> documentation that can be read without the help of a specific IDE (for
> example, in any web browser).

Have you tried gnathtml? Or is that the same as the GPS documentation 
function? (I don't use GPS.)

For an example of gnathtml output you can peek at 
http://www.bound-t.com/download/aux/find_marks-html/index.htm. Start in 
the file find_marks.adb.

-- 
Niklas Holsti
Tidorum Ltd
niklas holsti tidorum fi
       .      @       .

Re: Ada documentation tools.

[Maciej Sobczak]

On 15 Lis, 13:29, AdaMagica <christoph.gr...@eurocopter.com> wrote:

> > Formatting. Presentation is not only about content.
>
> Hm. How can a tool improve bad formatting in the code?

Every reasonable code editor does it without any problem. Some people
actually never format their code by hand and rely on tools to do that
for them.

> Format the code
> correctly in the first place.

Can I use a tool to do it?

And, while we're at it, what does it mean "correctly"? Correctly
according to your preferences or to mine? Tools can also automate the
transition between different conventions.

But formatting is not only about whitespace. It is also about colors,
fonts, text flow, and so on. Code can be also printed or rendered in
HTML browser - not necessarily as standalone content, but also as part
of wiki pages, docs, etc.

There are plenty of ways to "consume" the source code outside of the
IDE and visualizing its content in many different ways is an important
part of delivering the source code to users. Raw spec is not enough.

--
Maciej Sobczak * http://www.inspirel.com

Re: Ada documentation tools.

[AdaMagica]

On 15 Nov., 14:06, Maciej Sobczak <see.my.homep...@gmail.com> wrote:
> On 15 Lis, 13:29, AdaMagica <christoph.gr...@eurocopter.com> wrote:
>
> > > Formatting. Presentation is not only about content.
>
> > Hm. How can a tool improve bad formatting in the code?
>
> Every reasonable code editor does it without any problem. Some people
> actually never format their code by hand and rely on tools to do that
> for them.
>
> > Format the code
> > correctly in the first place.
>
> Can I use a tool to do it?
>
> And, while we're at it, what does it mean "correctly"? Correctly
> according to your preferences or to mine? Tools can also automate the
> transition between different conventions.
>
> But formatting is not only about whitespace. It is also about colors,
> fonts, text flow, and so on. Code can be also printed or rendered in
> HTML browser - not necessarily as standalone content, but also as part
> of wiki pages, docs, etc.
>
> There are plenty of ways to "consume" the source code outside of the
> IDE and visualizing its content in many different ways is an important
> part of delivering the source code to users. Raw spec is not enough.
>
> --
> Maciej Sobczak *http://www.inspirel.com

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.

Re: Ada documentation tools.

[Georg Bauhaus]

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.

Re: Ada documentation tools.

[Peter C. Chapin]

On 2010-11-15 07:56, Niklas Holsti wrote:

> For an example of gnathtml output you can peek at
> http://www.bound-t.com/download/aux/find_marks-html/index.htm. Start in
> the file find_marks.adb.

That looks rather different than what I get out of GPS (v4.4.1). I'm not
sure what tool GPS is using in the background.

Peter

Re: Ada documentation tools.

[Peter C. Chapin]

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

Re: Ada documentation tools.

[Marc A. Criley]

On 11/15/2010 06:38 AM, AdaMagica wrote:

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

Uh...yeah.  We have lots of design and model reviewers, from several 
different disciplines, with only the designers/developers actually 
needing to generate them.  Exporting to HTML for browsing works very 
well, and is far more economical than buying a license for every person 
that needs to review design artifacts, as well as having to train 
everyone on the project on how to use a particular design tool. Most 
people come pre-trained when it comes to clicking hyperlinks :-)

Marc A. Criley
McKae Software

Re: Ada documentation tools.

[Yannick Duchêne (Hibou57)]

Le Mon, 15 Nov 2010 15:56:31 +0100, Georg Bauhaus  
<rm.dash-bauhaus@futureapps.de> a écrit:
> tools that address proper comments.  And do it formally,
> otherwise documentation is necessarily bricolage.
You really have that word in English too, “bricolage”. Funny.

I have opened a similar topic some times ago, it was not welcomed as I  
expected. I would like too, to have a standard to tag Ada comments. At the  
time of that older topic, I though about Doxygen, which seemed to be  
enough language neutral, but did not go further nor I really evaluated it.  
May be the Java convention could be re-used straight as-is in Ada, as many  
people know these.

-- 
Si les chats miaulent et font autant de vocalises bizarres, c’est pas pour  
les chiens.

“I am fluent in ASCII” [Warren 2010]

Re: Ada documentation tools.

[Marco]

On Monday, November 15, 2010 4:33:19 PM UTC-7, Peter C. Chapin wrote:


> 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.

Whitebox vs Blackbox is important - comments on the algorithm used for example belong in the body not the spec since it could change without affecting the caller