Thoughts on doxygen for internal documentation

Thoughts on doxygen for internal documentation

[Diego Novillo]

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.

Re: Thoughts on doxygen for internal documentation

[Phil Edwards]

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

Re: Thoughts on doxygen for internal documentation

[law]

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

Re: Thoughts on doxygen for internal documentation

[Diego Novillo]

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.

Re: Thoughts on doxygen for internal documentation

[law]

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

Re: Thoughts on doxygen for internal documentation

[Theodore Papadopoulo]

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
 --------------------------------------------------------------------

Re: Thoughts on doxygen for internal documentation

[Gabriel Dos Reis]

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

Re: Thoughts on doxygen for internal documentation

[law]

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

Re: Thoughts on doxygen for internal documentation

[Andrew Haley]

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.

Re: Thoughts on doxygen for internal documentation

[Toon Moene]

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)

Re: Thoughts on doxygen for internal documentation

[Joel Sherrill]

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

Re: Thoughts on doxygen for internal documentation

[Marc Espie]

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) :)

Re: Thoughts on doxygen for internal documentation

[Andrew Haley]

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.

Re: Thoughts on doxygen for internal documentation

[Theodore Papadopoulo]

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
 --------------------------------------------------------------------

Re: Thoughts on doxygen for internal documentation

[Daniel Egger]

[-- 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 --]

Re: Thoughts on doxygen for internal documentation

[Daniel Berlin]

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
>

Re: Thoughts on doxygen for internal documentation

[Daniel Egger]

[-- 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 --]

Re: Thoughts on doxygen for internal documentation

[Diego Novillo]

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.

Re: Thoughts on doxygen for internal documentation

[Gabriel Dos Reis]

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

Re: Thoughts on doxygen for internal documentation

[law]

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

Re: Thoughts on doxygen for internal documentation

[Daniel Berlin]

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
>

Re: Thoughts on doxygen for internal documentation

[Kurt Wall]

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.

Re: Thoughts on doxygen for internal documentation

[Joseph S. Myers]

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

Re: Thoughts on doxygen for internal documentation

[Tony Finch]

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.

Re: Thoughts on doxygen for internal documentation

[Daniel Egger]

[-- 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 --]

Re: Thoughts on doxygen for internal documentation

[Robert Dewar]

> 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.