[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: TexInfo -> Doxygen
From: |
Robert T. Short |
Subject: |
Re: TexInfo -> Doxygen |
Date: |
Mon, 24 Jan 2011 14:30:46 -0800 |
User-agent: |
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.9.1.4) Gecko/20091017 SeaMonkey/2.0 |
John W. Eaton wrote:
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.
Exactly. Overall flow, structure, and interface is the really important
part of documentation. Code details fall out pretty quickly if you
understand what is supposed to be happening.
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.
Again, exactly. Even in commercial products with money and motivation
trying to document all of the internals always, always falls apart when
crunch time comes. While I agree with Jordi in principle, in practice
if we don't keep things simple and lightweight the "octave internals
documentation project" is doomed.
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
If there is something I can do to help get started, I will. Let me know.
Bob
- Re: TexInfo -> Doxygen, (continued)
- Re: TexInfo -> Doxygen, John W. Eaton, 2011/01/24
- Re: TexInfo -> Doxygen, Jordi Gutiérrez Hermoso, 2011/01/24
- Re: TexInfo -> Doxygen, John W. Eaton, 2011/01/24
- Re: TexInfo -> Doxygen, Søren Hauberg, 2011/01/24
- Re: TexInfo -> Doxygen, Robert T. Short, 2011/01/24
- Re: TexInfo -> Doxygen, Jordi Gutiérrez Hermoso, 2011/01/24
- Re: TexInfo -> Doxygen, John W. Eaton, 2011/01/24
- Re: TexInfo -> Doxygen, Robert T. Short, 2011/01/24
- Re: TexInfo -> Doxygen, Jordi Gutiérrez Hermoso, 2011/01/24
- Re: TexInfo -> Doxygen, John W. Eaton, 2011/01/24
- Re: TexInfo -> Doxygen,
Robert T. Short <=
- Re: TexInfo -> Doxygen, Søren Hauberg, 2011/01/24