Re: TexInfo -> Doxygen

[John W. Eaton]

On 24-Jan-2011, Jordi Gutiérrez Hermoso wrote:

| 3) I prefer too much detail to none at all.

You can prefer it if you like, but I disagree with the idea that there
is no such thing as too much detail.  When you have people commenting
every line of source code, it becomes ridiculous.  I used to work on a
project where many obvious things were documented unnecessarily, but
big picture items were not documented at all.  The sources were full of

  C Return to calling function.
        RETURN

but there was no clue at all about how major interfaces worked.

Now, clearly Octave could use some more information about why some
things are the way they are, and how the overall structure is tied
together, but we don't need to clutter the sources with a lot of
useless comments out of some misguided idea that every function should
be documented in some standard format.  Really, it is not necessary
and can be harmful if it creates more work for people who have to
maintain the code later.

So, I suggest that you start by submitting some patches that show what
you intend to do so we can decide whether to continue down this path.
You are more likely to gain support from me if you make incremental
changes and ask for feedback along the way rather than creating a
jumbo patch that is too large to easily review.

jwe