* Thoughts on doxygen for internal documentation @ 2003-01-15 23:48 Diego Novillo 2003-01-16 10:47 ` Phil Edwards ` (2 more replies) 0 siblings, 3 replies; 26+ messages in thread From: Diego Novillo @ 2003-01-15 23:48 UTC (permalink / raw) To: gcc I have tried using doxygen to document the tree-ssa API. Given the prevalent documentation style in GCC, I find some of the markers rather intrusive. For instance, it insists that documentation for arguments should be preceded by @param. It also doesn't understand that we refer to the argument names in capitals. This breaks the flow of the comment and makes it harder to read. I don't mind the @brief marker that it wants for adding one liner descriptions in the TOC. But again, I'd rather not add it. What I find nice are the @file markers for describing the file. What is really useful about doxygen is all the cross referencing and html pages it builds. Also, we don't really need to mark up everything for doxygen to be useful. It's enough that we delimit the function comments with /** */. For the tree-ssa branch, I'd like to propose the following: 1- When writing the preceding documentation for a function, data structure or variable, delimit it with /** */. This way, doxygen will add it when generating documentation. 2- For new files use the @file and @brief markers to provide a brief description for the file. No other markers should be required. It would be nice if the rest of the compiler used the /** */ comments, but for now I'm happy if we just do it for the tree-ssa files. Thoughts? Diego. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-15 23:48 Thoughts on doxygen for internal documentation Diego Novillo @ 2003-01-16 10:47 ` Phil Edwards 2003-01-16 18:12 ` law 2003-01-17 11:05 ` Tony Finch 2 siblings, 0 replies; 26+ messages in thread From: Phil Edwards @ 2003-01-16 10:47 UTC (permalink / raw) To: Diego Novillo; +Cc: gcc On Wed, Jan 15, 2003 at 02:46:27PM -0500, Diego Novillo wrote: > For instance, it insists that documentation for arguments should > be preceded by @param. It also doesn't understand that we refer > to the argument names in capitals. This breaks the flow of the > comment and makes it harder to read. libstdc++-v3 has to uglify parameter names, but the names given to @param don't actually have to match any of the names used in the code. I take advantage of that to keep the documentation from being soaked with underscores, e.g., @param foo whatever @param bar whatever ... void standard_function (int __foo, int __bar) ... Phil -- I would therefore like to posit that computing's central challenge, viz. "How not to make a mess of it," has /not/ been met. - Edsger Dijkstra, 1930-2002 ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-15 23:48 Thoughts on doxygen for internal documentation Diego Novillo 2003-01-16 10:47 ` Phil Edwards @ 2003-01-16 18:12 ` law 2003-01-16 18:14 ` Diego Novillo 2003-01-16 20:03 ` Joseph S. Myers 2003-01-17 11:05 ` Tony Finch 2 siblings, 2 replies; 26+ messages in thread From: law @ 2003-01-16 18:12 UTC (permalink / raw) To: Diego Novillo; +Cc: gcc In message <20030115194627.GA25096@tornado.toronto.redhat.com>, Diego Novillo w rites: >I have tried using doxygen to document the tree-ssa API. Given >the prevalent documentation style in GCC, I find some of the >markers rather intrusive. > >For instance, it insists that documentation for arguments should >be preceded by @param. It also doesn't understand that we refer >to the argument names in capitals. This breaks the flow of the >comment and makes it harder to read. > >I don't mind the @brief marker that it wants for adding one liner >descriptions in the TOC. But again, I'd rather not add it. What >I find nice are the @file markers for describing the file. > >What is really useful about doxygen is all the cross referencing >and html pages it builds. Also, we don't really need to mark up >everything for doxygen to be useful. It's enough that we delimit >the function comments with /** */. > >For the tree-ssa branch, I'd like to propose the following: > >1- When writing the preceding documentation for a function, data > structure or variable, delimit it with /** */. This way, > doxygen will add it when generating documentation. > > >2- For new files use the @file and @brief markers to provide a > brief description for the file. > >No other markers should be required. It would be nice if the >rest of the compiler used the /** */ comments, but for now I'm >happy if we just do it for the tree-ssa files. Actually, I wouldn't go with doxygen stuff at all unless it's been OK'd for the rest of the compiler proper. jeff ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:12 ` law @ 2003-01-16 18:14 ` Diego Novillo 2003-01-16 18:16 ` law 2003-01-17 4:00 ` Kurt Wall 2003-01-16 20:03 ` Joseph S. Myers 1 sibling, 2 replies; 26+ messages in thread From: Diego Novillo @ 2003-01-16 18:14 UTC (permalink / raw) To: law; +Cc: gcc On Thu, 16 Jan 2003, Jeff Law wrote: > Actually, I wouldn't go with doxygen stuff at all unless it's been > OK'd for the rest of the compiler proper. > Oh, well, OK. In reality all I we *really* need is to delimit comments with /** */. All the rest is up to doxygen to figure out. So, even if the comments are not delimited with /** */, doxygen is still useful. Let me rephrase the question then. Would it be OK to start documenting major functions and data structures with /** */ instead of /* */? I will still request its usage in tree-ssa-branch. If the final decision is not to use the additional '*' in comments, a sed script can easily remove them from the tree-ssa files before we merge to mainline. Thanks. Diego. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:14 ` Diego Novillo @ 2003-01-16 18:16 ` law 2003-01-16 18:18 ` Theodore Papadopoulo ` (2 more replies) 2003-01-17 4:00 ` Kurt Wall 1 sibling, 3 replies; 26+ messages in thread From: law @ 2003-01-16 18:16 UTC (permalink / raw) To: Diego Novillo; +Cc: gcc In message <20030116173437.GA2593@tornado.toronto.redhat.com>, Diego Novillo wr ites: >On Thu, 16 Jan 2003, Jeff Law wrote: > >> Actually, I wouldn't go with doxygen stuff at all unless it's been >> OK'd for the rest of the compiler proper. >> >Oh, well, OK. In reality all I we *really* need is to delimit >comments with /** */. All the rest is up to doxygen to figure >out. So, even if the comments are not delimited with /** */, >doxygen is still useful. > >Let me rephrase the question then. Would it be OK to start >documenting major functions and data structures with /** */ >instead of /* */? Same answer. If /** is acceptable for the rest of the compiler proper, then I'd go with it on tree-ssa. If it isn't acceptable, then I would avoid it as it just makes more work for you. Yes, you can find/change them with sed, but what's the point. I'll note that /** is contrary to the GNU coding standards. jeff ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:16 ` law @ 2003-01-16 18:18 ` Theodore Papadopoulo 2003-01-16 18:57 ` Gabriel Dos Reis ` (5 more replies) 2003-01-16 18:20 ` Diego Novillo 2003-01-16 18:25 ` Daniel Berlin 2 siblings, 6 replies; 26+ messages in thread From: Theodore Papadopoulo @ 2003-01-16 18:18 UTC (permalink / raw) To: law; +Cc: Diego Novillo, gcc law@redhat.com said: > I'll note that /** is contrary to the GNU coding standards. Not really answering in this thread, but this kind of comment make me often wonder whether these coding conventions are sometimes reviewed and updated. The world is changing around us, the rules should change accordingly.... As an example, I always wondered why the rule of 80 columns is still that strict. IMHO often code can be more readable using longer lines (still with a reasonnable limit, just an higher one). Yes I know, some people still have a very old 80 columns VT100, but those cannot be that many ? Indeed, mail reader sometimes have this 80 limit constraints, but then problems with line wrapping by mailers happen also with 80 columns... So why keeping this constraints and not updating it to something more sensible such as eg 132 colums. In some sense, this is exactly the same debate as the one of ANSI C conversion. Should we keep rules that were certainly very sensible at the time they were written but that are now obsolete at least for 99% of the users/developpers. Not really willing to launch a debate, but just wondering why these rules are so rigid... -------------------------------------------------------------------- Theodore Papadopoulo Email: Theodore.Papadopoulo@sophia.inria.fr Tel: (33) 04 92 38 76 01 -------------------------------------------------------------------- ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:18 ` Theodore Papadopoulo @ 2003-01-16 18:57 ` Gabriel Dos Reis 2003-01-16 19:11 ` law ` (4 subsequent siblings) 5 siblings, 0 replies; 26+ messages in thread From: Gabriel Dos Reis @ 2003-01-16 18:57 UTC (permalink / raw) To: Theodore Papadopoulo; +Cc: law, Diego Novillo, gcc Theodore Papadopoulo <Theodore.Papadopoulo@sophia.inria.fr> writes: | As an example, I always wondered why the rule of 80 columns is still | that strict. Because the guy down the wall still uses tty with 80 columns? ;-) -- Gaby ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:18 ` Theodore Papadopoulo 2003-01-16 18:57 ` Gabriel Dos Reis @ 2003-01-16 19:11 ` law 2003-01-16 19:53 ` Andrew Haley 2003-01-16 23:36 ` Toon Moene 2003-01-16 19:18 ` Joel Sherrill ` (3 subsequent siblings) 5 siblings, 2 replies; 26+ messages in thread From: law @ 2003-01-16 19:11 UTC (permalink / raw) To: Theodore Papadopoulo; +Cc: Diego Novillo, gcc In message <200301161803.h0GI3DYV018983@mururoa.inria.fr>, Theodore Papadopoulo writes: > > >law@redhat.com said: >> I'll note that /** is contrary to the GNU coding standards. > >Not really answering in this thread, but this kind of comment make me >often wonder whether these coding conventions are sometimes reviewed >and updated. The world is changing around us, the rules should change >accordingly.... > >As an example, I always wondered why the rule of 80 columns is still >that strict. IMHO often code can be more readable using longer lines >(still with a reasonnable limit, just an higher one). Yes I know, some >people still have a very old 80 columns VT100, but those cannot be >that many ? Indeed, mail reader sometimes have this 80 limit constraints, >but then problems with line wrapping by mailers happen also with 80 >columns... So why keeping this constraints and not updating it to >something more sensible such as eg 132 colums. I've known GCC hackers (who shall remain nameless) who didn't use graphical displays. Instead they used 24x80 screens and linux's virtual terminals. Hell, I still do it myself when traveling. jeff ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 19:11 ` law @ 2003-01-16 19:53 ` Andrew Haley 2003-01-16 23:36 ` Toon Moene 1 sibling, 0 replies; 26+ messages in thread From: Andrew Haley @ 2003-01-16 19:53 UTC (permalink / raw) To: law; +Cc: Theodore Papadopoulo, Diego Novillo, gcc law@redhat.com writes: > I've known GCC hackers (who shall remain nameless) who didn't use > graphical displays. Instead they used 24x80 screens and linux's > virtual terminals. Hell, I still do it myself when traveling. At least one gcc developer tiles his display with nine (or was it twelve?) 80x24 xterms... Andrew. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 19:11 ` law 2003-01-16 19:53 ` Andrew Haley @ 2003-01-16 23:36 ` Toon Moene 1 sibling, 0 replies; 26+ messages in thread From: Toon Moene @ 2003-01-16 23:36 UTC (permalink / raw) To: law; +Cc: Theodore Papadopoulo, Diego Novillo, gcc law@redhat.com wrote: > I've known GCC hackers (who shall remain nameless) who didn't use > graphical displays. Instead they used 24x80 screens and linux's > virtual terminals. Hell, I still do it myself when traveling. Well, there's a very good reason for limiting terminal screens to 80 columns. If you do `set number' in vi, you'll immediately notice if you're exceeding the 72nd column for Fortran code. [ ... Here it comes: :-) ] -- Toon Moene - mailto:toon@moene.indiv.nluug.nl - phoneto: +31 346 214290 Saturnushof 14, 3738 XG Maartensdijk, The Netherlands Maintainer, GNU Fortran 77: http://gcc.gnu.org/onlinedocs/g77_news.html GNU Fortran 95: http://gcc-g95.sourceforge.net/ (under construction) ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:18 ` Theodore Papadopoulo 2003-01-16 18:57 ` Gabriel Dos Reis 2003-01-16 19:11 ` law @ 2003-01-16 19:18 ` Joel Sherrill 2003-01-16 19:35 ` Marc Espie ` (2 subsequent siblings) 5 siblings, 0 replies; 26+ messages in thread From: Joel Sherrill @ 2003-01-16 19:18 UTC (permalink / raw) To: Theodore Papadopoulo; +Cc: law, Diego Novillo, gcc Theodore Papadopoulo wrote: > > law@redhat.com said: > > I'll note that /** is contrary to the GNU coding standards. I have used Doxygen on a recent project and must say that it is pretty nifty. I know our customer was impressed by the D size plotter printout of the object structure in the application. It is a useful application. The only liability is that the GNU Project has software in many languages and Doxygen does not support but a handful of them. > As an example, I always wondered why the rule of 80 columns is still > that strict. IMHO often code can be more readable using longer lines > (still with a reasonnable limit, just an higher one). Yes I know, some > people still have a very old 80 columns VT100, but those cannot be > that many ? Indeed, mail reader sometimes have this 80 limit constraints, > but then problems with line wrapping by mailers happen also with 80 > columns... So why keeping this constraints and not updating it to > something more sensible such as eg 132 colums. Not to pick but I have been around a while now (first UNIX experience around 1983) and haven't personally touched a real terminal in at least 7 years for any purpose. But 80 columns is still a reasonable restriction and we enforce it in my company's coding standards. Our Xterm's may be any width we like but printing code that is wider than 80 columns is troublesome. Yes you can reduce the font but that only makes it harder to read. Personally I like to use mpage to print 2 pages of program text to a page at 80 columns wide. > -------------------------------------------------------------------- > Theodore Papadopoulo > Email: Theodore.Papadopoulo@sophia.inria.fr Tel: (33) 04 92 38 76 01 > -------------------------------------------------------------------- -- Joel Sherrill, Ph.D. Director of Research & Development joel@OARcorp.com On-Line Applications Research Ask me about RTEMS: a free RTOS Huntsville AL 35805 Support Available (256) 722-9985 ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:18 ` Theodore Papadopoulo ` (2 preceding siblings ...) 2003-01-16 19:18 ` Joel Sherrill @ 2003-01-16 19:35 ` Marc Espie 2003-01-16 19:37 ` Andrew Haley 2003-01-17 0:26 ` Daniel Egger 5 siblings, 0 replies; 26+ messages in thread From: Marc Espie @ 2003-01-16 19:35 UTC (permalink / raw) To: gcc In article <200301161803.h0GI3DYV018983@mururoa.inria.fr> you write: >As an example, I always wondered why the rule of 80 columns is still >that strict. IMHO often code can be more readable using longer lines >(still with a reasonnable limit, just an higher one). Yes I know, some >people still have a very old 80 columns VT100, but those cannot be >that many ? Indeed, mail reader sometimes have this 80 limit constraints, >but then problems with line wrapping by mailers happen also with 80 >columns... So why keeping this constraints and not updating it to >something more sensible such as eg 132 colums. 80 columns still has lots of advantages. with 80 columns lines, I can put two xterms of a readable font size side by side on my laptop. Not so with 132 columns. I think that 80 columns keep programmers honest. When you find out that your code is consistently flushed against the right border, it's probably because the nesting of your code is too deep to make sense. But, hey, of course, the gnu coding standards, at least the formatting part, make no sense to a large proportion of the coding community anyways (the linux kernel, and the bsd code being two prime examples of code that does not follow those conventions) :) ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:18 ` Theodore Papadopoulo ` (3 preceding siblings ...) 2003-01-16 19:35 ` Marc Espie @ 2003-01-16 19:37 ` Andrew Haley 2003-01-16 19:57 ` Theodore Papadopoulo 2003-01-17 0:26 ` Daniel Egger 5 siblings, 1 reply; 26+ messages in thread From: Andrew Haley @ 2003-01-16 19:37 UTC (permalink / raw) To: Theodore Papadopoulo; +Cc: law, Diego Novillo, gcc Theodore Papadopoulo writes: > > As an example, I always wondered why the rule of 80 columns is still > that strict. 2 reasons: * Most tools, at least the ones that I use, default to 80 cols. Having to resize is maddening. * It's easier to read. Look at a newspaper (about 40 chars wide) or a book (up to 80). Typesetters know not to exceed that, so books with wide pages are split into two columns. Andrew. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 19:37 ` Andrew Haley @ 2003-01-16 19:57 ` Theodore Papadopoulo 0 siblings, 0 replies; 26+ messages in thread From: Theodore Papadopoulo @ 2003-01-16 19:57 UTC (permalink / raw) To: Andrew Haley; +Cc: law, Diego Novillo, gcc aph@redhat.com said: >> As an example, I always wondered why the rule of 80 columns is still >> that strict. Please do not focus on the 80 columns debate... I do not really care, even though my opinion appeared clearly. I was just asking for a review of the standards to put them in sync with current practice (times the importance of the contribution of the developper giving his opinion, since I do not expect anyone to give a lot of weight on my personnal feelings since my contributions are unfortunately basically zero). The important question is doxygen or not or something else but the /** should not be a rigid constraint if (and only if) the tool is considered as valuable. Again doxygen is just an example. Formatting constraints (whatever they are) are good as long as they are not a blocking factor. Then, on the 80 columns stuff (which I should not have raised perhaps since it's not the best example), let me just add that newspaper and code are quite different ;-P !!! Maybe we should try formatting the files in 2 columns of forty characters, but I guess gcc would have difficulty in gobbling those files :-) -------------------------------------------------------------------- Theodore Papadopoulo Email: Theodore.Papadopoulo@sophia.inria.fr Tel: (33) 04 92 38 76 01 -------------------------------------------------------------------- ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:18 ` Theodore Papadopoulo ` (4 preceding siblings ...) 2003-01-16 19:37 ` Andrew Haley @ 2003-01-17 0:26 ` Daniel Egger 2003-01-17 16:15 ` Daniel Berlin 5 siblings, 1 reply; 26+ messages in thread From: Daniel Egger @ 2003-01-17 0:26 UTC (permalink / raw) To: Theodore Papadopoulo; +Cc: gcc [-- Attachment #1: Type: text/plain, Size: 1191 bytes --] Am Don, 2003-01-16 um 19.03 schrieb Theodore Papadopoulo: > As an example, I always wondered why the rule of 80 columns is still > that strict. IMHO often code can be more readable using longer lines > (still with a reasonnable limit, just an higher one). Yes I know, some > people still have a very old 80 columns VT100, but those cannot be > that many ? Indeed, mail reader sometimes have this 80 limit constraints, > but then problems with line wrapping by mailers happen also with 80 > columns... So why keeping this constraints and not updating it to > something more sensible such as eg 132 colums. I really doubt that having more characters per line increases readability, rather I claim *really* needing that much space means that someone is doing something outright stupid and not well-thought, sometimes because he/she/it simply doesn't know better, but forcing her/him/it to break the line also enforces reconsidering the source sometimes leading to easier and/or more effective code. No, my terminal is not limited to 80 characters though I appreciate that measure because I can fit exactly 4 80x25 in X on my screen. :) -- Servus, Daniel [-- Attachment #2: Dies ist ein digital signierter Nachrichtenteil --] [-- Type: application/pgp-signature, Size: 189 bytes --] ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-17 0:26 ` Daniel Egger @ 2003-01-17 16:15 ` Daniel Berlin 2003-01-19 5:09 ` Daniel Egger 0 siblings, 1 reply; 26+ messages in thread From: Daniel Berlin @ 2003-01-17 16:15 UTC (permalink / raw) To: Daniel Egger; +Cc: Theodore Papadopoulo, gcc On Thu, 16 Jan 2003, Daniel Egger wrote: > Am Don, 2003-01-16 um 19.03 schrieb Theodore Papadopoulo: > > > As an example, I always wondered why the rule of 80 columns is still > > that strict. IMHO often code can be more readable using longer lines > > (still with a reasonnable limit, just an higher one). Yes I know, some > > people still have a very old 80 columns VT100, but those cannot be > > that many ? Indeed, mail reader sometimes have this 80 limit constraints, > > but then problems with line wrapping by mailers happen also with 80 > > columns... So why keeping this constraints and not updating it to > > something more sensible such as eg 132 colums. > > I really doubt that having more characters per line increases > readability, rather I claim *really* needing that much space means > that someone is doing something outright stupid and not well-thought, > sometimes because he/she/it simply doesn't know better, but forcing > her/him/it to break the line also enforces reconsidering the source > sometimes leading to easier and/or more effective code. Not necessarily. There are some pretty long macro names in gcc. Let's take, for instance, on the rtlopt-branch, the VAR_LOCATION notes. To compare two of the locations in them will take if (rtx_equal_p (NOTE_VAR_LOCATION_LOC (var1), NOTE_VAR_LOCATION_LOC (var2)) That's 77 characters. Imagine what happens if you are storing these notes in some other structure. You basically have to store them to temporary, just so one can read the code. But it *really* needs that much space to do something non-stupid, and well thought out. You can't come up with a better name (NOTE_VAR_LOC_LOC would be a bit confusing, and they are notes describing variable locations, so what else would you call them). You can't change the fact that we have to store them, etc. Not that this line shouldn't be split, i'm just disputing that anything really needing that much space is somehow bad code. I also don't think that storing things to temporaries with shorter names just so the line looks nicer is "more effective" code, just nicer looking code. But that's what one ends up doing a lot. Especially when you end up with C that wants to do a lot of what C++ does, so you have tons of macros or accessor functions that you could use a shorter name for in C++ (IE in member functions), but can't in C. > > No, my terminal is not limited to 80 characters though I appreciate > that measure because I can fit exactly 4 80x25 in X on my screen. :) > > -- > Servus, > Daniel > ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-17 16:15 ` Daniel Berlin @ 2003-01-19 5:09 ` Daniel Egger 0 siblings, 0 replies; 26+ messages in thread From: Daniel Egger @ 2003-01-19 5:09 UTC (permalink / raw) To: Daniel Berlin; +Cc: gcc [-- Attachment #1: Type: text/plain, Size: 780 bytes --] Am Fre, 2003-01-17 um 10.10 schrieb Daniel Berlin: > Not necessarily. > There are some pretty long macro names in gcc. [ long explanation omitted ] Your example is absolutely reasonable and I totally agree that it's not wise to bend over and invent whatever obfuscated programming has to offer just to keep it below 80 characters. Though at the same time > if (rtx_equal_p (NOTE_VAR_LOCATION_LOC (var1), NOTE_VAR_LOCATION_LOC (var2)) is a perfect example for code which is IMHO easy to misread because from glancing over it one might miss what exactly happens to be the condition. If in doubt I'd rather write your example as: if (rtx_equal_p (NOTE_VAR_LOCATION_LOC (var1), NOTE_VAR_LOCATION_LOC (var2)) -- Servus, Daniel [-- Attachment #2: Dies ist ein digital signierter Nachrichtenteil --] [-- Type: application/pgp-signature, Size: 189 bytes --] ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:16 ` law 2003-01-16 18:18 ` Theodore Papadopoulo @ 2003-01-16 18:20 ` Diego Novillo 2003-01-16 18:27 ` Gabriel Dos Reis 2003-01-16 18:29 ` law 2003-01-16 18:25 ` Daniel Berlin 2 siblings, 2 replies; 26+ messages in thread From: Diego Novillo @ 2003-01-16 18:20 UTC (permalink / raw) To: law; +Cc: gcc On Thu, 16 Jan 2003, Jeff Law wrote: > >Let me rephrase the question then. Would it be OK to start > >documenting major functions and data structures with /** */ > >instead of /* */? > > Same answer. If /** is acceptable for the rest of the compiler > proper, then I'd go with it on tree-ssa. If it isn't acceptable, > We are running around in circles. You still have not given me *your* opinion! :) > I'll note that /** is contrary to the GNU coding standards. > Yes, I know. That's why I'm asking. I need to gather opinions on whether we should ammend the coding standards to request comments starting with /** to make them more doxygen friendly. Would people in this list endorse such a change to the coding standards? A meta question. Is this the right forum to debate the issue? If not, what is the process for making changes to the coding standards? Thanks. Diego. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:20 ` Diego Novillo @ 2003-01-16 18:27 ` Gabriel Dos Reis 2003-01-16 18:29 ` law 1 sibling, 0 replies; 26+ messages in thread From: Gabriel Dos Reis @ 2003-01-16 18:27 UTC (permalink / raw) To: Diego Novillo; +Cc: law, gcc Diego Novillo <dnovillo@redhat.com> writes: | A meta question. Is this the right forum to debate the issue? I would answer: No. But then, we're affected as well. If you wanted my opinion, I'm not convinced by the move to doxygening the compiler. But, heh.. -- Gaby ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:20 ` Diego Novillo 2003-01-16 18:27 ` Gabriel Dos Reis @ 2003-01-16 18:29 ` law 1 sibling, 0 replies; 26+ messages in thread From: law @ 2003-01-16 18:29 UTC (permalink / raw) To: Diego Novillo; +Cc: gcc In message <20030116180431.GA2997@tornado.toronto.redhat.com>, Diego Novillo wr ites: >On Thu, 16 Jan 2003, Jeff Law wrote: > >> >Let me rephrase the question then. Would it be OK to start >> >documenting major functions and data structures with /** */ >> >instead of /* */? >> >> Same answer. If /** is acceptable for the rest of the compiler >> proper, then I'd go with it on tree-ssa. If it isn't acceptable, >> >We are running around in circles. You still have not given me >*your* opinion! :) That would be because I don't have a personal opinion. I feel no need or desire to have an opinion about coding standards. I just adapt myself to whatever the standards are for the project I'm working on. Meaning that I'm going to support the GNU standards for GCC since GCC is part of the GNU project. [ Now since most of the work I've done for the last 10 years has been on GNU stuff, my ability to read/write kernel-normal-form from my BSD days has diminished somewhat :-) ] >Yes, I know. That's why I'm asking. I need to gather opinions >on whether we should ammend the coding standards to request >comments starting with /** to make them more doxygen friendly. > >Would people in this list endorse such a change to the coding >standards? > >A meta question. Is this the right forum to debate the issue? >If not, what is the process for making changes to the coding >standards? This is a good a place to start as any. If you want to change the standards, I'd use this forum to gather arguments to support your position and a "fan base", then take it up with the FSF. jeff ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:16 ` law 2003-01-16 18:18 ` Theodore Papadopoulo 2003-01-16 18:20 ` Diego Novillo @ 2003-01-16 18:25 ` Daniel Berlin 2 siblings, 0 replies; 26+ messages in thread From: Daniel Berlin @ 2003-01-16 18:25 UTC (permalink / raw) To: law; +Cc: Diego Novillo, gcc On Thursday, January 16, 2003, at 12: > I'll note that /** is contrary to the GNU coding standards. > What gives you this idea? It doesn't specify what to delimit comments with, actually, although it uses /* in the examples. I read through all of section 5, and can't find anything saying comments must start with /*, rather than /**. > jeff > ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:14 ` Diego Novillo 2003-01-16 18:16 ` law @ 2003-01-17 4:00 ` Kurt Wall 1 sibling, 0 replies; 26+ messages in thread From: Kurt Wall @ 2003-01-17 4:00 UTC (permalink / raw) To: gcc Feigning erudition, Diego Novillo wrote: % On Thu, 16 Jan 2003, Jeff Law wrote: % % > Actually, I wouldn't go with doxygen stuff at all unless it's been % > OK'd for the rest of the compiler proper. % > % Oh, well, OK. In reality all I we *really* need is to delimit % comments with /** */. All the rest is up to doxygen to figure % out. So, even if the comments are not delimited with /** */, % doxygen is still useful. % % Let me rephrase the question then. Would it be OK to start % documenting major functions and data structures with /** */ % instead of /* */? % % I will still request its usage in tree-ssa-branch. If the final % decision is not to use the additional '*' in comments, a sed % script can easily remove them from the tree-ssa files before we % merge to mainline. Not that my vote counts for anything, but I would oppose doxygenification for (at least) two reason. First, I don't find doxygen'ed documentation particularly illuminating to read -- I can just as well read the source code and the header files if I need API references. If one takes the time to write meaningful, useful documentation in the code using /** */, then the desired goal, writing useful documentation, is already achieved. If, on the other hand, inaccurate comments or downright useless comments are embedded in a doxygen-friendly way (that is, using /** */), then all you've achieved is creating lousy documentation that is easy to extract and format nicely. ;-) Secondly, and let me be clear that I'm not referring to anyone in particular, doxygen and similar automated methods of documenting code speak more to laziness and sloppiness than to producing high quality documentation. Of course, manual^H^H^H^H^H^Hinfo pages can be just as poorly written as automatically-generated documentation, but one has to try harder to write lousy documentation when creating an info file from scratch -- doxygen and kin just make it easier to create awful documentation. My two farthings... Kurt -- A diplomat is a man who can convince his wife she'd look stout in a fur coat. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-16 18:12 ` law 2003-01-16 18:14 ` Diego Novillo @ 2003-01-16 20:03 ` Joseph S. Myers 1 sibling, 0 replies; 26+ messages in thread From: Joseph S. Myers @ 2003-01-16 20:03 UTC (permalink / raw) To: gcc On Thu, 16 Jan 2003 law@redhat.com wrote: > Actually, I wouldn't go with doxygen stuff at all unless it's been > OK'd for the rest of the compiler proper. I don't see a particular problem with doxygen to provide additional documentation (and cross-referencing, etc.) for internals, as long as the aim is still maintained that all the actual interfaces for authors of front ends and back ends (as opposed to details of internals at a lower level - for which documentation is still useful and for which doxygen may provide better structure than plain comments) should be documented in the internals manual proper (gccint.texi and files included from it). -- Joseph S. Myers jsm28@cam.ac.uk ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-15 23:48 Thoughts on doxygen for internal documentation Diego Novillo 2003-01-16 10:47 ` Phil Edwards 2003-01-16 18:12 ` law @ 2003-01-17 11:05 ` Tony Finch 2003-01-18 22:21 ` Daniel Egger 2 siblings, 1 reply; 26+ messages in thread From: Tony Finch @ 2003-01-17 11:05 UTC (permalink / raw) To: dnovillo; +Cc: gcc Diego Novillo <dnovillo@redhat.com> wrote: >I have tried using doxygen to document the tree-ssa API. Given >the prevalent documentation style in GCC, I find some of the >markers rather intrusive. The advantage of doxygen's comment format is that it's based on other standards like JavaDoc and Qt. I don't know how well it maintains compatibility with them. >What is really useful about doxygen is all the cross referencing >and html pages it builds. Yes, the output is nice. I've tried to use Doxygen for C code, which it is advertised to support although it is constructed from a C++ point of view. Its understanding of the language is very vague (the parser is a bunch-o-regexps wrapped in lex -- not yacc!) and when it gets things wrong it's hard to fix. I still want to be able to like it, though. Tony. -- f.a.n.finch <dot@dotat.at> http://dotat.at/ NORTHWEST FITZROY SOLE LUNDY FASTNET: WESTERLY OR SOUTHWESTERLY 5 TO 7, OCCASIONALLY GALE 8 AT FIRST. OCCASIONAL RAIN. MODERATE OR GOOD. ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation 2003-01-17 11:05 ` Tony Finch @ 2003-01-18 22:21 ` Daniel Egger 0 siblings, 0 replies; 26+ messages in thread From: Daniel Egger @ 2003-01-18 22:21 UTC (permalink / raw) To: Tony Finch; +Cc: gcc [-- Attachment #1: Type: text/plain, Size: 838 bytes --] Am Fre, 2003-01-17 um 06.26 schrieb Tony Finch: > The advantage of doxygen's comment format is that it's based > on other standards like JavaDoc and Qt. I don't know how well > it maintains compatibility with them. I rather dislike JavaDoc. For me it's incomprehensible because the interesting information is drown in a sea of declarations which simply shouldn't matter and if they do, the source itself is a much better reference (if it isn't it's definitely time to refactor the code). In short: The concept is sound but the implementation sucks. However if it helps others it'd be definitely to support it, especially if all one has to do is add a single unintrusive character per commentblock. The issue seems to be solved differently however if I read Diegos mail correctly.... -- Servus, Daniel [-- Attachment #2: Dies ist ein digital signierter Nachrichtenteil --] [-- Type: application/pgp-signature, Size: 189 bytes --] ^ permalink raw reply [flat|nested] 26+ messages in thread
* Re: Thoughts on doxygen for internal documentation
@ 2003-01-18 16:17 Robert Dewar
0 siblings, 0 replies; 26+ messages in thread
From: Robert Dewar @ 2003-01-18 16:17 UTC (permalink / raw)
To: Theodore.Papadopoulo, law; +Cc: dnovillo, gcc
> As an example, I always wondered why the rule of 80 columns is still
> that strict. IMHO often code can be more readable using longer lines
> (still with a reasonnable limit, just an higher one). Yes I know, some
> people still have a very old 80 columns VT100, but those cannot be
> that many ? Indeed, mail reader sometimes have this 80 limit constraints,
> but then problems with line wrapping by mailers happen also with 80
> columns... So why keeping this constraints and not updating it to
> something more sensible such as eg 132 colums.
It is really useful to maintain the 80 column rule, otherwise you get
into a mess in using screen real estate, or messing with horizontal
scrolling in an editor.
^ permalink raw reply [flat|nested] 26+ messages in thread
end of thread, other threads:[~2003-01-18 17:03 UTC | newest] Thread overview: 26+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2003-01-15 23:48 Thoughts on doxygen for internal documentation Diego Novillo 2003-01-16 10:47 ` Phil Edwards 2003-01-16 18:12 ` law 2003-01-16 18:14 ` Diego Novillo 2003-01-16 18:16 ` law 2003-01-16 18:18 ` Theodore Papadopoulo 2003-01-16 18:57 ` Gabriel Dos Reis 2003-01-16 19:11 ` law 2003-01-16 19:53 ` Andrew Haley 2003-01-16 23:36 ` Toon Moene 2003-01-16 19:18 ` Joel Sherrill 2003-01-16 19:35 ` Marc Espie 2003-01-16 19:37 ` Andrew Haley 2003-01-16 19:57 ` Theodore Papadopoulo 2003-01-17 0:26 ` Daniel Egger 2003-01-17 16:15 ` Daniel Berlin 2003-01-19 5:09 ` Daniel Egger 2003-01-16 18:20 ` Diego Novillo 2003-01-16 18:27 ` Gabriel Dos Reis 2003-01-16 18:29 ` law 2003-01-16 18:25 ` Daniel Berlin 2003-01-17 4:00 ` Kurt Wall 2003-01-16 20:03 ` Joseph S. Myers 2003-01-17 11:05 ` Tony Finch 2003-01-18 22:21 ` Daniel Egger 2003-01-18 16:17 Robert Dewar
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).