Re: Ada and Doxygen

[Vadim Godunko <vgodunko@gmail.com>]

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!