Re: TexInfo -> Doxygen

[Jordi Gutiérrez Hermoso]

I'm going to address a bunch of concerns at once regarding use Doxygen
in Octave:

1) We already require people to update docstrings when they mess with
user-visible functions. Messing with internal functions should be no
reason for "internal undocumented function". And docstrings going out
of synch with their code is always a problem whether the function is
interpreter-visible or not. At least Doxygen automates the part of
what class/functions are available and their bare-bones API, so that
much can't go out of synch.

2) Doxygen's syntax is *very* similar to TeXinfo's. In fact, Doxygen
can use pretty much the same (La)TeX commands as TeXinfo, and you can
even use the same command prefix if you want ("@"), amongst other
choices.

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

4) We already publish the API as bare-bones Doxygen docs, and that
hasn't incurred an armageddon of users complaining over why the API
isn't stable. We get the occasional person finding that something that
worked in a previous version doesn't anymore, and last time that
happened it turned out to be an actual issue in Octave for which jwe
later wrote patch (a83bad07f7e3).

5) We strive for ABI compatibility with oct files across stable
releases, and API compatibility is a prerequisite for that. We could
mark functions as not part of the oct interface, here be dragons,
don't call this function, blah blah blah, but that's no reason to
avoid documenting it as if documentation could ever hurt anyone.

6) We *could* in fact write all of the documentation in Doxygen. But
why bother, we already have pretty good TeXinfo docs for m-scripts,
functions callable from the interpreter, and the overall manual.
There's no need to do that.

tl;dr Doxygen is nice, don't be afraid, the water is just fine,
horrible things aren't gonna happen if we start writing documentation
for undocumented internal functions.

- Jordi G. H.