Ada and Doxygen

Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Hello Ada designers,

Do someones or some teams miss Doxygen support for Ada ?
Is there a market or potential fundings for this functionalities ?


-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Georg Bauhaus]

Hibou57 (Yannick Duchï¿œne) schrieb:
> 
> Hello Ada designers,
> 
> Do someones or some teams miss Doxygen support for Ada ?
> Is there a market or potential fundings for this functionalities ?

Not being a designer, I still think there already
is something serving as an even better solution
(in terms of real-world usability).

Using facilities of AI05-0183,


 procedure Pop (Cap : Bottle_of_Beer)
   with Brief => "produces the sound of opening a bottle",
        Pre'Class => not Is_Open (Bottle);

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Wed, 24 Feb 2010 11:10:16 +0100, Georg Bauhaus  
<rm.dash-bauhaus@futureapps.de> a écrit:
> Not being a designer, I still think there already
> is something serving as an even better solution
> (in terms of real-world usability).
>
> Using facilities of AI05-0183,
>
>
>  procedure Pop (Cap : Bottle_of_Beer)
>    with Brief => "produces the sound of opening a bottle",
>         Pre'Class => not Is_Open (Bottle);
We all wait for that, but it is not there, and anyway, it's source and  
source will never have the expected properties of a document (like  
publication, browsing).

I was also seeking for something like this for other purpose I will not  
talk about for the moment (let say it has to deal with verbosity and  
contexts which are foreign to sources).

Jean-Pierre has pointed a worth to see solution by the way (on the french  
c.l.a, where I first mistakenly sent the same question) : he pointed about  
NaturalDocs, which seems promising : http://www.naturaldocs.org/
Supports numerous languages : this is helpful when integration of  
different solutions is to be handled.

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Georg Bauhaus]

Hibou57 (Yannick Duchï¿œne) schrieb:
> Le Wed, 24 Feb 2010 11:10:16 +0100, Georg Bauhaus
> <rm.dash-bauhaus@futureapps.de> a ï¿œcrit:
>> Not being a designer, I still think there already
>> is something serving as an even better solution
>> (in terms of real-world usability).
>>
>> Using facilities of AI05-0183,
>>
>>
>>  procedure Pop (Cap : Bottle_of_Beer)
>>    with Brief => "produces the sound of opening a bottle",
>>         Pre'Class => not Is_Open (Bottle);
> We all wait for that, but it is not there, and anyway, it's source and
> source will never have the expected properties of a document (like
> publication, browsing).

Two remarks.

1) Ada "aspects" and solutions similar to NaturalDocs (which looks
a bit like a mix of Java comments and Python comments) need not
be mutually exclusive. With aspects, however, the Ada grammer
will guide the compiler, the comipler will mark errors,
and, importantly, do so without too much comment syntax awareness :
If there is an identifier in a "comment aspect" and this identifier
is not visible where the subprogram is declared (of which the comment
is an aspect), then the compiler proper will diagnose this error.


|  procedure Pop (Cap : Bottle_of_Beer)
|    with Brief => "produces the sound of opening `Bottle`",
|         Pre'Class => not Is_Open (Bottle);

$ future.ada.compiler example.ada
(C) The Hot Air Dptmt. 20XX

example.ada:14:60: Identifier "Bottle" is not known here
example.ada:15:45: Identifier "Bottle" is not known here

Therefore I think there is a way to, finally, force
us programmers to keep comments and code in sync
and have the compiler tell us if we don't!

2) The first example of NaturalDocs is telling, I'd say.
Effectively, is shows two syntaxes for declaring subprograms:
- one that is explaining what is going on, what the parameters
are etc. and
- the other, which needs the first syntax in addition because
it features the typical {}-languages' obfuscating syntax
for declaring things...

Can we do better?

Re: Ada and Doxygen

[Stephen Leake]

"Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes:

> Do someones or some teams miss Doxygen support for Ada ?
> Is there a market or potential fundings for this functionalities ?

I have never been happy with the documentation produced by Doxygen for
C++ projects. I'd much rather have the actual source code, in an
editor/viewer that supports full navigation (like GPS or Emacs Ada
mode for Ada).

Once you separate the comments from the actual code, the quality
degrades. 

-- 
-- Stephe

Re: Ada and Doxygen

[Stephen Leake]

"Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes:

> Le Wed, 24 Feb 2010 11:10:16 +0100, Georg Bauhaus
> <rm.dash-bauhaus@futureapps.de> a écrit:
>> Not being a designer, I still think there already
>> is something serving as an even better solution
>> (in terms of real-world usability).
>>
>> Using facilities of AI05-0183,
>>
>>
>>  procedure Pop (Cap : Bottle_of_Beer)
>>    with Brief => "produces the sound of opening a bottle",
>>         Pre'Class => not Is_Open (Bottle);
> We all wait for that, but it is not there, and anyway, it's source and
> source will never have the expected properties of a document (like
> publication, browsing).

Browsing is better for Ada in GPS or Emacs Ada mode; you can get to
_all_ of the source, not just what the Doxygen viewer has access to. 

what do you mean by "publication"?

> I was also seeking for something like this for other purpose I will
> not  talk about for the moment (let say it has to deal with verbosity
> and  contexts which are foreign to sources).

"contexts foreign to sources" requires something much better than
Doxygen can provide. It has to abstract and summarize the whole
program; Doxygen comments are all local.

-- 
-- Stephe

Re: Ada and Doxygen

[Marco]

On Feb 25, 5:18 am, Stephen Leake <stephen_le...@stephe-leake.org>
wrote:
> "Hibou57 (Yannick Duchêne)" <yannick_duch...@yahoo.fr> writes:

>
> "contexts foreign to sources" requires something much better than
> Doxygen can provide. It has to abstract and summarize the whole
> program; Doxygen comments are all local.

  Yes for all but the most trivial applications (the term program is
too simplistic) some sort of external documentation is needed. Can
this some-how be tied to the code so a simple refactor of a package
name or public parameter would just be updated automatically?

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Thu, 25 Feb 2010 13:18:10 +0100, Stephen Leake  
<stephen_leake@stephe-leake.org> a écrit:
> "contexts foreign to sources" requires something much better than
> Doxygen can provide. It has to abstract and summarize the whole
> program; Doxygen comments are all local.
>

Seems you are reading in my mind : that's what LP (Literate Programming)  
is for ;) (TBH, I'm thinking about something different, while still after  
that, let say that LP is a convenient picture for me).

Note : I was not to advertise for Doxygen, I was just prospecting about  
possible requests for it, because I first though about it as a possible  
solution for something else, and on the way, found peoples who were  
complaining there is no support for Ada in Doxygen. I understand this also  
vary from people to people (and also note Doxygen was not created with Ada  
in mind anyway and it's probably far to be its first target).

> Browsing is better for Ada in GPS or Emacs Ada mode; you can get to
> _all_ of the source, not just what the Doxygen viewer has access to.

If I may have a comment about a "detail" : while GPS provides some way to  
travel across sources, this does not compare to a browsable set of  
document which are browsable by nature (is it the good word for the french  
"par essence" ?) and where links are managed and edited as part of the  
content, just like words and sentences are. If the content of a document  
and its interpretation depends on the application you use to view it, then  
this is no more a document (I mean, links are not really part of this  
"document" and don't takes part of it). And indeed, it depends (after your  
example) on GPS or Emacs mode (this is inferred from the document, just  
like would be a list of words or an automatic index, which may not be  
meaningful.... because automatic)

Further more, this kind of browsing does not allow pre-designed navigation  
paths (this is mainly random browsing -- random here, has the same meaning  
as with random file access), still because browsing in not a first  
property of sources, and this will never be, because this does not have to  
be, just because documents and sources are different things with different  
purposes.

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Thu, 25 Feb 2010 14:31:47 +0100, Marco <prenom_nomus@yahoo.com> a écrit:
>   Yes for all but the most trivial applications (the term program is
> too simplistic) some sort of external documentation is needed.
While you may also guess/feel it's needed, even facing a trivial  
application. You can infer the efficiency of a method from a trivial case,  
as long as you mind is not tied to this trivial case (that comment is  
anecdotal, but it was in my mind, and it is for long)

> Can
> this some-how be tied to the code so a simple refactor of a package
> name or public parameter would just be updated automatically?
Please, I need to understand more about what you were to say : do you mean  
update of the documentation or automatic refactoring operations while  
editing source ? What kind of synch were you thinking about exactly ?

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Tero Koskinen]

Hi,

On Wed, 24 Feb 2010 09:39:35 +0100 Hibou57 (Yannick Duchêne) wrote:
> 
> Hello Ada designers,
> 
> Do someones or some teams miss Doxygen support for Ada ?
> Is there a market or potential fundings for this functionalities ?

Adabrowse has been working for me. Although it is tied to
ASIS (and therefore GNAT).

URL:
http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/

-- 
Tero Koskinen - http://iki.fi/tero.koskinen/

Re: Ada and Doxygen

[Stephen Leake]

"Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes:

> <stephen_leake@stephe-leake.org> a écrit:
>
>> Browsing is better for Ada in GPS or Emacs Ada mode; you can get to
>> _all_ of the source, not just what the Doxygen viewer has access to.
>
> If I may have a comment about a "detail" : while GPS provides some way
> to  travel across sources, this does not compare to a browsable set of
> document which are browsable by nature (is it the good word for the
> french  "par essence" ?) and where links are managed and edited as
> part of the  content, just like words and sentences are. 

I don't agree. 

What, exactly, is missing in Emacs Ada mode?

Actually, I have one item; an easy way to see the inherited operations
of a type. For example, the Qt manuals show that. I have no idea
whether the Qt manuals are produced by a tool.

If I were to use a tool to produce separate documentation for Ada
source code, I'd start with AdaBrowse
(http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/); it uses ASIS, so
it starts with all the information the compiler has.

> If the content of a document and its interpretation depends on the
> application you use to view it, then this is no more a document (I
> mean, links are not really part of this "document" and don't takes
> part of it). 

For a general "document", I agree. For Ada source code, a tool that
specifically understands the Ada syntax is better; that's what GPS and
Emacs Ada mode are - they use the cross index information output by
the GNAT Ada compiler.

> And indeed, it depends (after your example) on GPS or Emacs mode
> (this is inferred from the document, just like would be a list of
> words or an automatic index, which may not be meaningful.... because
> automatic)

I don't understand your point here.

> Further more, this kind of browsing does not allow pre-designed
> navigation  paths (this is mainly random browsing -- random here, has
> the same meaning  as with random file access), 

Well, yes. 

If you want to write a tutorial, that's a separate document, not
source code. 

> still because browsing in not a first property of sources, 

"Browsing" is heavily overloaded. A "source code browser" uses only
information in the sources to generate the browsing links; in that
case, I think it is fair to say "source code browsing information is a
first property of sources". Of course, Ada provides much better
browsing information than C or Assembler.

> and this will never be, because this does not have to be, just
> because documents and sources are different things with different
> purposes.

What is the list of requirements for this hypothetical browsing tool
you want to use?

-- 
-- Stephe

Re: Ada and Doxygen

[Gautier write-only]

Did you try the documentation tool shipped with GPS (the GNAT
Programming Studio) ?
It is looking nice. But I am not an expert in that field. Opinions ?
_________________________________________________________
Gautier's Ada programming -- http://sf.net/users/gdemont/
NB: For a direct answer, e-mail address on the Web site!

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Fri, 26 Feb 2010 09:49:12 +0100, Stephen Leake  
<stephen_leake@stephe-leake.org> a écrit:
> I don't agree.
>
> What, exactly, is missing in Emacs Ada mode?
>
> Actually, I have one item; an easy way to see the inherited operations
> of a type. For example, the Qt manuals show that. I have no idea
> whether the Qt manuals are produced by a tool.
>
> If I were to use a tool to produce separate documentation for Ada
> source code, I'd start with AdaBrowse
> (http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/); it uses ASIS, so
> it starts with all the information the compiler has.
This is kind of dump, that's not what I was talking about (I know  
AdaBrowse ...and there are others I forget the name BTW).

> For a general "document", I agree. For Ada source code, a tool that
> specifically understands the Ada syntax is better; that's what GPS and
> Emacs Ada mode are - they use the cross index information output by
> the GNAT Ada compiler.
Any way, this is the same principle (same comment as the latter).

>> And indeed, it depends (after your example) on GPS or Emacs mode
>> (this is inferred from the document, just like would be a list of
>> words or an automatic index, which may not be meaningful.... because
>> automatic)
>
> I don't understand your point here.
Let me help you to guess with a question : do you use debuggers ? (you may  
answer "yes" or "no" and add any comment which comes in your mind about it)

>> Further more, this kind of browsing does not allow pre-designed
>> navigation  paths (this is mainly random browsing -- random here, has
>> the same meaning  as with random file access),
>
> Well, yes.
>
> If you want to write a tutorial, that's a separate document, not
> source code.
That's closer.
Why did you use the word “ tutorial ” ? (just want to know, as this choice  
may be potentially relevant)

> What is the list of requirements for this hypothetical browsing tool
> you want to use?
Browsing is not the main purpose. The purpose is at understanding, and  
browsing is just a required thing for that. I was trying to tell browsing  
more or less randomly is not the same as traveling along a path which was  
provided on purpose with something in mind.


-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Vadim Godunko]

On Feb 26, 11:49 am, Stephen Leake <stephen_le...@stephe-leake.org>
wrote:
>
> Actually, I have one item; an easy way to see the inherited operations
> of a type. For example, the Qt manuals show that. I have no idea
> whether the Qt manuals are produced by a tool.
>
I found Qt's documentation excellent. It is generated by the tool, see
tools/qdoc3 in source code package. It would be nice to have such tool
for Ada, but it is not as simple to do as it seems for the first look.
Some reason are complexity of Ada language, absence of "class" scope,
existing "good practice". For example, all parts of documentation is
in the .cpp files in Qt, which makes .h files clean; opposite is
GNAT's style where all comments are around of entities in
specifications, which makes it simple to process but also makes
impossible to see all amount of package's entities on one page :-( The
sadly news is ARG seems to approve GNAT's style for future versions of
RM :-(

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Fri, 26 Feb 2010 11:52:07 +0100, Gautier write-only  
<gautier_niouzes@hotmail.com> a écrit:
> Did you try the documentation tool shipped with GPS (the GNAT
> Programming Studio) ?
Yes, I know it : let say this is a better AdaBrowse.

This does not add anything at understanding things. I mainly see it as a  
kind of enormous pop-up menu with big number of choices.

Note : as I said yesterday, I was not to advertise for Doxygen or any  
others in this area. When I opened this topic, I wanted to know if there  
were requests about it, thinking I could provide this if there was (was  
some request). But I initially came to be interested in Doxygen for an  
other indirect reason.

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Fri, 26 Feb 2010 19:43:03 +0100, Vadim Godunko <vgodunko@gmail.com> a  
écrit:
> I found Qt's documentation excellent. It is generated by the tool, see
> tools/qdoc3 in source code package.
Is there a way to see that without installing Qt libraries ? I had a quick  
look to read it on the web but found nothing.
Do you know a link ?

> It would be nice to have such tool
> for Ada, but it is not as simple to do as it seems for the first look.

> Some reason are complexity of Ada language, absence of "class" scope,
Side note : do you know the Ada rationale about it is that Ada have  
package scope instead of class scope ? ;)

> existing "good practice". For example, all parts of documentation is
> in the .cpp files in Qt, which makes .h files clean;
I guess I will not be able to understand before I ever have a chance to  
read this docs. However, just right now, I'm a bit surprised to read  
something about mixing .cpp, which is implementation part, with .h, which  
is specification part, from a user point of view. Or may be you're one of  
the Qt implementors ?

> opposite is
> GNAT's style where all comments are around of entities in
> specifications, which makes it simple to process but also makes
> impossible to see all amount of package's entities on one page :-( The
> sadly news is ARG seems to approve GNAT's style for future versions of
> RM :-(
Are you talking about merging all definitions provided in multiple package  
on a single page ? I'm not sure I've understood. Is that it ?

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Vadim Godunko]

On Feb 26, 10:02 pm, Hibou57 (Yannick Duchêne)
<yannick_duch...@yahoo.fr> wrote:
> Le Fri, 26 Feb 2010 19:43:03 +0100, Vadim Godunko <vgodu...@gmail.com> a  
> écrit:> I found Qt's documentation excellent. It is generated by the tool, see
> > tools/qdoc3 in source code package.
>
> Is there a way to see that without installing Qt libraries ? I had a quick  
> look to read it on the web but found nothing.
> Do you know a link ?
>
http://doc.qt.nokia.com/

But I can recommend to you to install Qt (or better install complete
Qt SDK to see Qt Creator also) and run Qt Assistant to read/navigate/
search around Qt's documentation, otherwise your imagination will be
incomplete.

> Side note : do you know the Ada rationale about it is that Ada have  
> package scope instead of class scope ? ;)
>
I don't. In my opinion absence of "class scope" is important language
design mistake. :-(

> > existing "good practice". For example, all parts of documentation is
> > in the .cpp files in Qt, which makes .h files clean;
>
> I guess I will not be able to understand before I ever have a chance to  
> read this docs. However, just right now, I'm a bit surprised to read  
> something about mixing .cpp, which is implementation part, with .h, which  
> is specification part, from a user point of view. Or may be you're one of  
> the Qt implementors ?
>
I am not Qt implementor, but I have some experience in use of it -
just because I was architect of QtAda binding and we was use it for
large project successfully.

> > opposite is
> > GNAT's style where all comments are around of entities in
> > specifications, which makes it simple to process but also makes
> > impossible to see all amount of package's entities on one page :-( The
> > sadly news is ARG seems to approve GNAT's style for future versions of
> > RM :-(
>
> Are you talking about merging all definitions provided in multiple package  
> on a single page ? I'm not sure I've understood. Is that it ?
>
No. We are known current GNAT's style for comments. Each package has a
description at the specification and each entity also has a
description below its declaration in the specification. GPS shows such
a comment in tooltips.

Qt's uses another way. There are no comments in headers at all. This
makes header files clean - it is very important for overview of the
class. All comments are placed in the implementation files. Special
tool parse both headers and implementation files, construct list of
classes, its methods/signals/slots/etc; then parse implementation
files and extracts description for each entity; links classes/methods/
slots/signals with their descriptions and construct complete
documentation in HTML form, which can be hosted somewhere or read by
browser. After that, another tool pack this documentation and all
related resources into the one "database" which can be registered in
the Qt Assistant to extend useful of it (Qt Assistant allows to do
full text search for example). And even it is not a last step, when
you use Qt Creator (IDE for Qt) and stay somewhere in the code, you
can click key and Qt Creator opens description of class/method you
stay on in the Qt Assistant documentation. It is very fast and useful!

Re: Ada and Doxygen

[sjw]

On Feb 26, 8:04 pm, Vadim Godunko <vgodu...@gmail.com> wrote:

> Qt's uses another way. There are no comments in headers at all. This
> makes header files clean - it is very important for overview of the
> class. All comments are placed in the implementation files. Special
> tool parse both headers and implementation files, construct list of
> classes, its methods/signals/slots/etc; then parse implementation
> files and extracts description for each entity; links classes/methods/
> slots/signals with their descriptions and construct complete
> documentation in HTML form, which can be hosted somewhere or read by
> browser. After that, another tool pack this documentation and all
> related resources into the one "database" which can be registered in
> the Qt Assistant to extend useful of it (Qt Assistant allows to do
> full text search for example). And even it is not a last step, when
> you use Qt Creator (IDE for Qt) and stay somewhere in the code, you
> can click key and Qt Creator opens description of class/method you
> stay on in the Qt Assistant documentation. It is very fast and useful!

I think you're saying that humans never need to read the .h files at
all, because tools make it possible to read the documentation where/
when you need to, in whatever form is most appropriate.

Nothing wrong with the outcome, but (it seems to me that) if the Qt
scheme had started from having full descriptions in the .h files and
the tools worked in that environment instead, you would be in
*exactly* the same position as now.

I find it frustrating going from the package specs in the LRM to
somewhere down-page which describes what the code actually means.

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Sat, 27 Feb 2010 08:46:24 +0100, sjw <simon.j.wright@mac.com> a écrit:
> I find it frustrating going from the package specs in the LRM to
> somewhere down-page which describes what the code actually means.
How and why do you feel it is frustrating precisely ? Is it a matter of  
amount of things to read ? Is it a matter of accessibility ? Or others ?

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Jacob Sparre Andersen]

Yannick Duch�ne wrote:
> Le Sat, 27 Feb 2010 08:46:24 +0100, sjw <simon.j.wright@mac.com> a
> �crit:

>> I find it frustrating going from the package specs in the LRM to
>> somewhere down-page which describes what the code actually means.
>
> How and why do you feel it is frustrating precisely ? Is it a matter
> of amount of things to read ? Is it a matter of accessibility ? Or
> others ?

It's slow and cumbersome.

Jacob
-- 
"Sleep is just a cheap substitute for coffee"

Re: Ada and Doxygen

[Stephen Leake]

"Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes:

>>> Further more, this kind of browsing does not allow pre-designed
>>> navigation  paths (this is mainly random browsing -- random here, has
>>> the same meaning  as with random file access),
>>
>> Well, yes.
>>
>> If you want to write a tutorial, that's a separate document, not
>> source code.
> That's closer.
> Why did you use the word “ tutorial ” ? (just want to know, as this
> choice  may be potentially relevant)

Most documents I read that have "pre-designed navigation paths" are
tutorials. Or fiction novels, in another domain.

Reference manuals should not have pre-designed paths; they should
allow random access, with lots of cross-references.

-- 
-- Stephe

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Sat, 27 Feb 2010 14:38:29 +0100, Jacob Sparre Andersen <sparre@nbi.dk>  
a écrit:
> It's slow and cumbersome.
That is one possible answer among others. However about this one, I would  
say “ if you want to create things fast, use script languages, not Ada ”.  
Doing fast requires to drop many things.

About the “ cumbersome ” qualifier, I would say the RM is far easier to  
read than it is easier to solve any original problem. If every thing could  
be as much precise and predictable as the RM is... (this could be better,  
but it is clearer than most other things).

It's not the less easy, because everything is already done for you there,  
someones (a lot of peoples) have already solved a lot of things for you in  
the reference. Reading the RM provides more solutions than troubles.

This is not a personal opinion or a personal feeling, this is an objective  
fact : when you have to create something, you are facing the unknown,  
while the RM is what is known. This is one of the least cumbersome thing  
(it requires time, true, but time is needed for good things to become  
mature or to have a stable enough figure of it in mind).

Hope I'm not going to much off-topic with that comment.

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Sat, 27 Feb 2010 15:00:18 +0100, Stephen Leake  
<stephen_leake@stephe-leake.org> a écrit:
> Most documents I read that have "pre-designed navigation paths" are
> tutorials. Or fiction novels, in another domain.
>
> Reference manuals should not have pre-designed paths; they should
> allow random access, with lots of cross-references.
What would you say about a handbook ?


-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Stephen Leake]

Vadim Godunko <vgodunko@gmail.com> writes:

> We are known current GNAT's style for comments. Each package has a
> description at the specification and each entity also has a
> description below its declaration in the specification. GPS shows such
> a comment in tooltips.
>
> Qt's uses another way. There are no comments in headers at all. This
> makes header files clean - it is very important for overview of the
> class. 

You are implying that the comments get in the way of an "overview".

That makes sense; if you are mostly familiar with a package, but
forget the exact names, or want to see if a particular function is
there, it would be useful to have a short list of just the functions.

Emacs supports this by hiding selected parts of the file; all
comments, for example. See hs-minor-mode (hs for hide-show). That also
hides blocks in bodies, but apparently it doesn't currently understand
Ada for that feature. I don't like the current keybindings, but that's
easy to fix.

> All comments are placed in the implementation files. Special tool
> parse both headers and implementation files, construct list of
> classes, its methods/signals/slots/etc; then parse implementation
> files and extracts description for each entity; links
> classes/methods/ slots/signals with their descriptions and construct
> complete documentation in HTML form, which can be hosted somewhere
> or read by browser. After that, another tool pack this documentation
> and all related resources into the one "database" which can be
> registered in the Qt Assistant to extend useful of it (Qt Assistant
> allows to do full text search for example). And even it is not a
> last step, when you use Qt Creator (IDE for Qt) and stay somewhere
> in the code, you can click key and Qt Creator opens description of
> class/method you stay on in the Qt Assistant documentation. It is
> very fast and useful!

This could be done for the Ada code by a tool similar to AdaBrowse,
and an Emacs key binding could pop up Qt Assistant from Ada code. 

If I start using QtAda more, I'll be motivated to do this.

-- 
-- Stephe

Re: Ada and Doxygen

[Randy Brukardt]

"Stephen Leake" <stephen_leake@stephe-leake.org> wrote in message 
news:umxywwfef.fsf@stephe-leake.org...
...
> If I were to use a tool to produce separate documentation for Ada
> source code, I'd start with AdaBrowse
> (http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/); it uses ASIS, so
> it starts with all the information the compiler has.

Unrelated comment: ASIS (as implemented today) provides only a small subset 
of the information that the compiler has about a unit. For example, a 
compiler will be able to trivially determine if a view of a subtype is 
limited or non-limited; doing so accurately in ASIS takes many hundreds of 
lines of code. And ASIS provides no way to determine data layout at all 
(this is an intentional omission - but surely it comes under "information 
the compiler has").

The purpose behind the new ASIS Semantic Subsystem is to make much more (but 
far less than all!) of that information available to ASIS applications. But 
how knows when (or if) that subsystem will be widely implemented.

                                Randy Brukardt.

Re: Ada and Doxygen

[Hibou57 (Yannick Duchêne)]

Le Thu, 04 Mar 2010 00:55:07 +0100, Randy Brukardt <randy@rrsoftware.com>  
a écrit:
> lines of code. And ASIS provides no way to determine data layout at all
> (this is an intentional omission - but surely it comes under "information
> the compiler has").
May be that's the reason why ASIS is named after the expression "Semantic  
Interface" ;)

-- 
No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just  
not lucky

Re: Ada and Doxygen

[Marco]

On Feb 26, 11:43 am, Vadim Godunko <vgodu...@gmail.com> wrote:
> On Feb 26, 11:49 am, Stephen Leake <stephen_le...@stephe-leake.org>
> wrote:

> For example, all parts of documentation is
> in the .cpp files in Qt, which makes .h files clean;

   or worthless - the whole idea of a module (package in Ada) spec is
to document what the caller needs to know and "hide" what the caller
doesn't need to know

 why should I be forced to read another document just to understand a
module's interface

  typical C and C++ programmers don't seem to "get" this concept

Re: Ada and Doxygen

[Yannick Duchêne (Hibou57)]

Le Wed, 24 Feb 2010 09:39:35 +0100, Hibou57 (Yannick Duchêne)  
<yannick_duchene@yahoo.fr> a écrit:

>
> Hello Ada designers,
>
> Do someones or some teams miss Doxygen support for Ada ?
> Is there a market or potential fundings for this functionalities ?
>
>

Seems someone at least already requested this:
http://sourceforge.net/mailarchive/message.php?msg_id=3319982

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

“I am fluent in ASCII” [Warren 2010]