Re: TexInfo -> Doxygen

[Robert T. Short]

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