Re: TexInfo -> Doxygen

[Søren Hauberg]

man, 24 01 2011 kl. 11:53 +1300, skrev Sean Young:
> I've recently been discussing with Jordi ways to get involved with the
> project, and it was agreed that a good place for me to start would be
> with documentation as it would give me a chance to explore the source
> files whilst I'm at it.

This sounds like an excellent idea :-)

> Jordi has suggested that the current TexInfo documentation be moved to
> Doxygen format inside the c++ files so this is what I will be starting
> with. If you'd like further details on what I'm up to, please ask
> either myself or Jordi.

As John noted, this is something that really needs to be discussed
before we can go ahead with the idea. While I would personally love
having easier accessible documentation for the C++ classes, there are
downsides to using Doxygen:

      * We currently do *not* have a stable API, i.e. we make no
        promises that the API does not change from release to release.
        Having more formal documentation might give the impression that
        the API is stable. This would at least have to be clearly stated
        in the docs.
      * By not having any documentation it is easier to hack the Octave
        source code as you don't really have to care about keeping the
        docs up to date.

There are probably other potential issues, but I just got out of bed, so
I'm not thinking straight yet... :-)

Søren