* Ada and Doxygen @ 2010-02-24 8:39 Hibou57 (Yannick Duchêne) 2010-02-24 10:10 ` Georg Bauhaus ` (4 more replies) 0 siblings, 5 replies; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-24 8:39 UTC (permalink / raw) 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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 8:39 Ada and Doxygen Hibou57 (Yannick Duchêne) @ 2010-02-24 10:10 ` Georg Bauhaus 2010-02-24 11:20 ` Hibou57 (Yannick Duchêne) 2010-02-25 12:12 ` Stephen Leake ` (3 subsequent siblings) 4 siblings, 1 reply; 28+ messages in thread From: Georg Bauhaus @ 2010-02-24 10:10 UTC (permalink / raw) Hibou57 (Yannick Duchï¿œne) schrieb: > > 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); ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 10:10 ` Georg Bauhaus @ 2010-02-24 11:20 ` Hibou57 (Yannick Duchêne) 2010-02-24 13:05 ` Georg Bauhaus 2010-02-25 12:18 ` Stephen Leake 0 siblings, 2 replies; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-24 11:20 UTC (permalink / raw) Le Wed, 24 Feb 2010 11:10:16 +0100, Georg Bauhaus <rm.dash-bauhaus@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). 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. -- No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just not lucky ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 11:20 ` Hibou57 (Yannick Duchêne) @ 2010-02-24 13:05 ` Georg Bauhaus 2010-02-25 12:18 ` Stephen Leake 1 sibling, 0 replies; 28+ messages in thread From: Georg Bauhaus @ 2010-02-24 13:05 UTC (permalink / raw) Hibou57 (Yannick Duchï¿œne) schrieb: > Le Wed, 24 Feb 2010 11:10:16 +0100, Georg Bauhaus > <rm.dash-bauhaus@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). 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? ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 11:20 ` Hibou57 (Yannick Duchêne) 2010-02-24 13:05 ` Georg Bauhaus @ 2010-02-25 12:18 ` Stephen Leake 2010-02-25 13:31 ` Marco 2010-02-25 14:56 ` Hibou57 (Yannick Duchêne) 1 sibling, 2 replies; 28+ messages in thread From: Stephen Leake @ 2010-02-25 12:18 UTC (permalink / raw) "Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes: > Le Wed, 24 Feb 2010 11:10:16 +0100, Georg Bauhaus > <rm.dash-bauhaus@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-25 12:18 ` Stephen Leake @ 2010-02-25 13:31 ` Marco 2010-02-25 15:02 ` Hibou57 (Yannick Duchêne) 2010-02-25 14:56 ` Hibou57 (Yannick Duchêne) 1 sibling, 1 reply; 28+ messages in thread From: Marco @ 2010-02-25 13:31 UTC (permalink / raw) On Feb 25, 5:18 am, Stephen Leake <stephen_le...@stephe-leake.org> 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? ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-25 13:31 ` Marco @ 2010-02-25 15:02 ` Hibou57 (Yannick Duchêne) 0 siblings, 0 replies; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-25 15:02 UTC (permalink / raw) Le Thu, 25 Feb 2010 14:31:47 +0100, Marco <prenom_nomus@yahoo.com> a écrit: > Yes for all but the most trivial applications (the term program is > too simplistic) some sort of external documentation is needed. While you may also guess/feel it's needed, even facing a trivial 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 ? -- No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just not lucky ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-25 12:18 ` Stephen Leake 2010-02-25 13:31 ` Marco @ 2010-02-25 14:56 ` Hibou57 (Yannick Duchêne) 2010-02-26 8:49 ` Stephen Leake 1 sibling, 1 reply; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-25 14:56 UTC (permalink / raw) Le Thu, 25 Feb 2010 13:18:10 +0100, Stephen Leake <stephen_leake@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. -- No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just not lucky ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-25 14:56 ` Hibou57 (Yannick Duchêne) @ 2010-02-26 8:49 ` Stephen Leake 2010-02-26 18:42 ` Hibou57 (Yannick Duchêne) ` (2 more replies) 0 siblings, 3 replies; 28+ messages in thread From: Stephen Leake @ 2010-02-26 8:49 UTC (permalink / raw) "Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes: > <stephen_leake@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 8:49 ` Stephen Leake @ 2010-02-26 18:42 ` Hibou57 (Yannick Duchêne) 2010-02-27 14:00 ` Stephen Leake 2010-02-26 18:43 ` Vadim Godunko 2010-03-03 23:55 ` Randy Brukardt 2 siblings, 1 reply; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-26 18:42 UTC (permalink / raw) Le Fri, 26 Feb 2010 09:49:12 +0100, Stephen Leake <stephen_leake@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 18:42 ` Hibou57 (Yannick Duchêne) @ 2010-02-27 14:00 ` Stephen Leake 2010-02-27 14:25 ` Hibou57 (Yannick Duchêne) 0 siblings, 1 reply; 28+ messages in thread From: Stephen Leake @ 2010-02-27 14:00 UTC (permalink / raw) "Hibou57 (Yannick Duchêne)" <yannick_duchene@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-27 14:00 ` Stephen Leake @ 2010-02-27 14:25 ` Hibou57 (Yannick Duchêne) 0 siblings, 0 replies; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-27 14:25 UTC (permalink / raw) Le Sat, 27 Feb 2010 15:00:18 +0100, Stephen Leake <stephen_leake@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 8:49 ` Stephen Leake 2010-02-26 18:42 ` Hibou57 (Yannick Duchêne) @ 2010-02-26 18:43 ` Vadim Godunko 2010-02-26 19:02 ` Hibou57 (Yannick Duchêne) 2010-03-06 13:41 ` Marco 2010-03-03 23:55 ` Randy Brukardt 2 siblings, 2 replies; 28+ messages in thread From: Vadim Godunko @ 2010-02-26 18:43 UTC (permalink / raw) On Feb 26, 11:49 am, Stephen Leake <stephen_le...@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 :-( ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 18:43 ` Vadim Godunko @ 2010-02-26 19:02 ` Hibou57 (Yannick Duchêne) 2010-02-26 20:04 ` Vadim Godunko 2010-03-06 13:41 ` Marco 1 sibling, 1 reply; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-26 19:02 UTC (permalink / raw) Le Fri, 26 Feb 2010 19:43:03 +0100, Vadim Godunko <vgodunko@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 19:02 ` Hibou57 (Yannick Duchêne) @ 2010-02-26 20:04 ` Vadim Godunko 2010-02-27 7:46 ` sjw 2010-02-27 14:25 ` Stephen Leake 0 siblings, 2 replies; 28+ messages in thread From: Vadim Godunko @ 2010-02-26 20:04 UTC (permalink / raw) 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! ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 20:04 ` Vadim Godunko @ 2010-02-27 7:46 ` sjw 2010-02-27 9:12 ` Hibou57 (Yannick Duchêne) 2010-02-27 14:25 ` Stephen Leake 1 sibling, 1 reply; 28+ messages in thread From: sjw @ 2010-02-27 7:46 UTC (permalink / raw) On Feb 26, 8:04 pm, Vadim Godunko <vgodu...@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. ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-27 7:46 ` sjw @ 2010-02-27 9:12 ` Hibou57 (Yannick Duchêne) 2010-02-27 13:38 ` Jacob Sparre Andersen 0 siblings, 1 reply; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-27 9:12 UTC (permalink / raw) Le Sat, 27 Feb 2010 08:46:24 +0100, sjw <simon.j.wright@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-27 9:12 ` Hibou57 (Yannick Duchêne) @ 2010-02-27 13:38 ` Jacob Sparre Andersen 2010-02-27 14:23 ` Hibou57 (Yannick Duchêne) 0 siblings, 1 reply; 28+ messages in thread From: Jacob Sparre Andersen @ 2010-02-27 13:38 UTC (permalink / raw) Yannick Duch�ne wrote: > Le Sat, 27 Feb 2010 08:46:24 +0100, sjw <simon.j.wright@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" ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-27 13:38 ` Jacob Sparre Andersen @ 2010-02-27 14:23 ` Hibou57 (Yannick Duchêne) 0 siblings, 0 replies; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-27 14:23 UTC (permalink / raw) Le Sat, 27 Feb 2010 14:38:29 +0100, Jacob Sparre Andersen <sparre@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 20:04 ` Vadim Godunko 2010-02-27 7:46 ` sjw @ 2010-02-27 14:25 ` Stephen Leake 1 sibling, 0 replies; 28+ messages in thread From: Stephen Leake @ 2010-02-27 14:25 UTC (permalink / raw) Vadim Godunko <vgodunko@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 18:43 ` Vadim Godunko 2010-02-26 19:02 ` Hibou57 (Yannick Duchêne) @ 2010-03-06 13:41 ` Marco 1 sibling, 0 replies; 28+ messages in thread From: Marco @ 2010-03-06 13:41 UTC (permalink / raw) On Feb 26, 11:43 am, Vadim Godunko <vgodu...@gmail.com> wrote: > 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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 8:49 ` Stephen Leake 2010-02-26 18:42 ` Hibou57 (Yannick Duchêne) 2010-02-26 18:43 ` Vadim Godunko @ 2010-03-03 23:55 ` Randy Brukardt 2010-03-04 6:56 ` Hibou57 (Yannick Duchêne) 2 siblings, 1 reply; 28+ messages in thread From: Randy Brukardt @ 2010-03-03 23:55 UTC (permalink / raw) "Stephen Leake" <stephen_leake@stephe-leake.org> wrote in message news:umxywwfef.fsf@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. ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-03-03 23:55 ` Randy Brukardt @ 2010-03-04 6:56 ` Hibou57 (Yannick Duchêne) 0 siblings, 0 replies; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-03-04 6:56 UTC (permalink / raw) Le Thu, 04 Mar 2010 00:55:07 +0100, Randy Brukardt <randy@rrsoftware.com> 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"). May be that's the reason why ASIS is named after the expression "Semantic Interface" ;) -- No-no, this isn't an oops ...or I hope (TM) - Don't blame me... I'm just not lucky ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 8:39 Ada and Doxygen Hibou57 (Yannick Duchêne) 2010-02-24 10:10 ` Georg Bauhaus @ 2010-02-25 12:12 ` Stephen Leake 2010-02-25 18:31 ` Tero Koskinen ` (2 subsequent siblings) 4 siblings, 0 replies; 28+ messages in thread From: Stephen Leake @ 2010-02-25 12:12 UTC (permalink / raw) "Hibou57 (Yannick Duchêne)" <yannick_duchene@yahoo.fr> writes: > 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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 8:39 Ada and Doxygen Hibou57 (Yannick Duchêne) 2010-02-24 10:10 ` Georg Bauhaus 2010-02-25 12:12 ` Stephen Leake @ 2010-02-25 18:31 ` Tero Koskinen 2010-02-26 10:52 ` Gautier write-only 2011-03-16 21:44 ` Yannick Duchêne (Hibou57) 4 siblings, 0 replies; 28+ messages in thread From: Tero Koskinen @ 2010-02-25 18:31 UTC (permalink / raw) Hi, 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/ ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 8:39 Ada and Doxygen Hibou57 (Yannick Duchêne) ` (2 preceding siblings ...) 2010-02-25 18:31 ` Tero Koskinen @ 2010-02-26 10:52 ` Gautier write-only 2010-02-26 18:50 ` Hibou57 (Yannick Duchêne) 2011-03-16 21:44 ` Yannick Duchêne (Hibou57) 4 siblings, 1 reply; 28+ messages in thread From: Gautier write-only @ 2010-02-26 10:52 UTC (permalink / raw) 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! ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-26 10:52 ` Gautier write-only @ 2010-02-26 18:50 ` Hibou57 (Yannick Duchêne) 0 siblings, 0 replies; 28+ messages in thread From: Hibou57 (Yannick Duchêne) @ 2010-02-26 18:50 UTC (permalink / raw) Le Fri, 26 Feb 2010 11:52:07 +0100, Gautier write-only <gautier_niouzes@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 ^ permalink raw reply [flat|nested] 28+ messages in thread
* Re: Ada and Doxygen 2010-02-24 8:39 Ada and Doxygen Hibou57 (Yannick Duchêne) ` (3 preceding siblings ...) 2010-02-26 10:52 ` Gautier write-only @ 2011-03-16 21:44 ` Yannick Duchêne (Hibou57) 4 siblings, 0 replies; 28+ messages in thread From: Yannick Duchêne (Hibou57) @ 2011-03-16 21:44 UTC (permalink / raw) Le Wed, 24 Feb 2010 09:39:35 +0100, Hibou57 (Yannick Duchêne) <yannick_duchene@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] ^ permalink raw reply [flat|nested] 28+ messages in thread
end of thread, other threads:[~2011-03-16 21:44 UTC | newest] Thread overview: 28+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2010-02-24 8:39 Ada and Doxygen Hibou57 (Yannick Duchêne) 2010-02-24 10:10 ` Georg Bauhaus 2010-02-24 11:20 ` Hibou57 (Yannick Duchêne) 2010-02-24 13:05 ` Georg Bauhaus 2010-02-25 12:18 ` Stephen Leake 2010-02-25 13:31 ` Marco 2010-02-25 15:02 ` Hibou57 (Yannick Duchêne) 2010-02-25 14:56 ` Hibou57 (Yannick Duchêne) 2010-02-26 8:49 ` Stephen Leake 2010-02-26 18:42 ` Hibou57 (Yannick Duchêne) 2010-02-27 14:00 ` Stephen Leake 2010-02-27 14:25 ` Hibou57 (Yannick Duchêne) 2010-02-26 18:43 ` Vadim Godunko 2010-02-26 19:02 ` Hibou57 (Yannick Duchêne) 2010-02-26 20:04 ` Vadim Godunko 2010-02-27 7:46 ` sjw 2010-02-27 9:12 ` Hibou57 (Yannick Duchêne) 2010-02-27 13:38 ` Jacob Sparre Andersen 2010-02-27 14:23 ` Hibou57 (Yannick Duchêne) 2010-02-27 14:25 ` Stephen Leake 2010-03-06 13:41 ` Marco 2010-03-03 23:55 ` Randy Brukardt 2010-03-04 6:56 ` Hibou57 (Yannick Duchêne) 2010-02-25 12:12 ` Stephen Leake 2010-02-25 18:31 ` Tero Koskinen 2010-02-26 10:52 ` Gautier write-only 2010-02-26 18:50 ` Hibou57 (Yannick Duchêne) 2011-03-16 21:44 ` Yannick Duchêne (Hibou57)
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox