Ada and Doxygen
in [ADA]
|
From: Hibou57 (Yannick Duchêne) on 26 Feb 2010 14:02 Le Fri, 26 Feb 2010 19:43:03 +0100, Vadim Godunko <vgodunko(a)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
From: Vadim Godunko on 26 Feb 2010 15:04 On Feb 26, 10:02 pm, Hibou57 (Yannick Duchêne) <yannick_duch...(a)yahoo.fr> wrote: > Le Fri, 26 Feb 2010 19:43:03 +0100, Vadim Godunko <vgodu...(a)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!
From: sjw on 27 Feb 2010 02:46 On Feb 26, 8:04 pm, Vadim Godunko <vgodu...(a)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.
From: Hibou57 (Yannick Duchêne) on 27 Feb 2010 04:12 Le Sat, 27 Feb 2010 08:46:24 +0100, sjw <simon.j.wright(a)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
From: Jacob Sparre Andersen on 27 Feb 2010 08:38
Yannick Duch�ne wrote: > Le Sat, 27 Feb 2010 08:46:24 +0100, sjw <simon.j.wright(a)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" |