Ada and Doxygen
in [ADA]
|
From: Stephen Leake on 26 Feb 2010 03:49 "Hibou57 (Yannick Duchêne)" <yannick_duchene(a)yahoo.fr> writes: > <stephen_leake(a)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
From: Gautier write-only on 26 Feb 2010 05:52 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!
From: Hibou57 (Yannick Duchêne) on 26 Feb 2010 13:42 Le Fri, 26 Feb 2010 09:49:12 +0100, Stephen Leake <stephen_leake(a)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
From: Vadim Godunko on 26 Feb 2010 13:43 On Feb 26, 11:49 am, Stephen Leake <stephen_le...(a)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 :-(
From: Hibou57 (Yannick Duchêne) on 26 Feb 2010 13:50
Le Fri, 26 Feb 2010 11:52:07 +0100, Gautier write-only <gautier_niouzes(a)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 |