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
Georg Bauhaus
>
> 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);
Hibou57 (Yannick Duchêne)
<rm.dash...@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);
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.
Georg Bauhaus
>> 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?
Stephen Leake
> 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
Stephen Leake
> Le Wed, 24 Feb 2010 11:10:16 +0100, Georg Bauhaus
> <rm.dash...@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
Marco
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?
Hibou57 (Yannick Duchêne)
<stephe...@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.
Hibou57 (Yannick Duchêne)
> Yes for all but the most trivial applications (the term program is
> too simplistic) some sort of external documentation is needed.
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 ?
Tero Koskinen
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/
Stephen Leake
> <stephe...@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
Gautier write-only
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!
Hibou57 (Yannick Duchêne)
<stephe...@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.
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.
Vadim Godunko
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.
>
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 :-(
Hibou57 (Yannick Duchêne)
<gautier...@hotmail.com> a écrit:
> Did you try the documentation tool shipped with GPS (the GNAT
> Programming Studio) ?
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.
Hibou57 (Yannick Duchêne)
écrit:
> I found Qt's documentation excellent. It is generated by the tool, see
> tools/qdoc3 in source code package.
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 ?
Vadim Godunko
<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 ?
>
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!
sjw
> 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.
Hibou57 (Yannick Duchêne)
> I find it frustrating going from the package specs in the LRM to
> somewhere down-page which describes what the code actually means.
amount of things to read ? Is it a matter of accessibility ? Or others ?
Jacob Sparre Andersen
>> 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"
Stephen Leake
>>> 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
Hibou57 (Yannick Duchêne)
a écrit:
> It's slow and cumbersome.
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.
Hibou57 (Yannick Duchêne)
<stephe...@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.
Stephen Leake
> 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
Randy Brukardt
news:umxyww...@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.
Hibou57 (Yannick Duchêne)
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").
Interface" ;)
Marco
> 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
Yannick Duchêne (Hibou57)
<yannick...@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]