Re: TexInfo -> Doxygen

[John W. Eaton]

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