Re: TexInfo -> Doxygen

[Robert T. Short]

John W. Eaton wrote:
> On 24-Jan-2011, Jordi Gutiérrez Hermoso wrote:
>
> | On 24 January 2011 01:35, John W. Eaton<address@hidden>  wrote:
> |
> |>  Octave is a GNU project, and the GNU project uses Texinfo for its
> |>  documentation.  Is there a way to generate Texinfo from Doxygen
> |>  markup?
> |
> |      http://www.stack.nl/~dimitri/doxygen/output.html
> |
> | So, not directly. But it has every other output format that TeXinfo
> | has.
>
> It does not have Info output.
>
> If you can generate all these other kinds of output, it seems that it
> should be fairly simple to generate Texinfo.
>
> | I thought this would be ok, since it's not stuff that should be
> | "in the manual", but a developer aid. Or is the idea to have a
> | separate manual?
>
> Long ago, the idea was to have a separate manual for the internals.
> But that has never happened as no one seems to want to work on it.
> There have been essentially no changes to the doc/liboctave/*.texi
> files in the last decade.
>
> I also share Søren's concerns.  Documenting the Octave sources will be
> a lot of work.  Extensively documenting the internals in a way that is
> meant to be published (even if only on the web) tends to imply that we
> have stable interfaces, when in fact, we don't.  Also, since we do
> tend to change the internals a lot over time, you would be placing an
> additional burden on anyone looking to improve the internals if they
> were also expected to keep the documentation up to date, and you're
> now adding the extra requirement of knowing Doxygen syntax just to be
> able to document internals (hey, people complain about Texinfo syntax
> which is quite simple, so I can complain about Doxygen, which seems
> much more cryptic to me).
>
> If we do decide to add Doxygen comments to the sources, then I think
> we need to have a plan.  Simply trying to document every function
> would not be helpful, and I think would be a waste of time.  I really
> don't want to see documenation for trivial functions.  The things that
> need to be documented are the more complex functions, or the overall
> intent and purpose of a class.
>
> Maybe you should post some examples of what you intend to do, then we
> can discuss whether we think it would be worthwhile to continue.
>
> jwe
>
>
>    
I would actually be willing to work on this, but I always felt that 
there was no real interest.  Maybe that is simply my misreading the 
situation.  Personally, I don't think software is complete without 
documentation.  I guess I have spent too many years managing commercial 
programs.  On the other hand this is something that folks like me with 
extremely limited time can do to help.


Just to contribute my thoughts to the discussion:


I don't think Doxygen is at all appropriate for documenting USER 
functions (i.e. the places where we have docstrings today) - that is 
unless the docstrings can be generated from the Doxygen.


I think the real use of Doxygen would be for documentation of 
internals.  The problems are manifold though, and in particular 
(partially repeating what John already said):

1.  If you try to document every little detail you will never finish and 
the result
     will be an overwhelming pile of useless junk.
2.  Each class must have a minimum level of detail - and personally I 
think the
     most useful thing is simply an overview of what the class does and how
     it goes about it is the most valuable thing of all.
3.  Everyone that mucks about with a documented class has to agree to make
     sure the documentation is up-to-date.  This is strongly influenced 
by items
     (1) and (2) - more work makes it less likely it will be done.  As 
soon as
     anybody fails in this task, the entire effort becomes wasted.

Some really valuable things that would come out of this effort though.  
First, I find UML (or SDL, take your pick) structure diagrams quite 
valuable, both in the design of complex systems and in understanding 
existing systems.  For some of the more complex subsystems, some action 
diagrams would be extremely valuable as well.  A further benefit is that 
pictures often expose design or concept flaws (and points out the GOOD 
things).

A second possible benefit has to do with attracting folks to help.  From 
experience I can tell you that unless you have a lot of time to spend 
understanding the octave code base it is quite difficult to make 
meaningful contributions - and then when you think you did a good thing 
you find out that some subtle issue made it a bad thing.  Some written 
documentation that leads a body through the process would be most 
helpful.  Again, the most valuable thing is to ensure that the 
documentation is really a PROCESS overview, not a document with lots and 
lots of details.

Just my two cents,

Bob