Ada and Doxygen
in [ADA]
|
From: Stephen Leake on 27 Feb 2010 09:00 "Hibou57 (Yannick Duchêne)" <yannick_duchene(a)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
From: Hibou57 (Yannick Duchêne) on 27 Feb 2010 09:23 Le Sat, 27 Feb 2010 14:38:29 +0100, Jacob Sparre Andersen <sparre(a)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
From: Hibou57 (Yannick Duchêne) on 27 Feb 2010 09:25 Le Sat, 27 Feb 2010 15:00:18 +0100, Stephen Leake <stephen_leake(a)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
From: Stephen Leake on 27 Feb 2010 09:25 Vadim Godunko <vgodunko(a)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
From: Randy Brukardt on 3 Mar 2010 18:55
"Stephen Leake" <stephen_leake(a)stephe-leake.org> wrote in message news:umxywwfef.fsf(a)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. |