Re: TexInfo -> Doxygen

[Søren Hauberg]

man, 24 01 2011 kl. 14:33 -0500, skrev John W. Eaton:
> 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.

All classes are equal, but some are more equal than others :-) By this I
mean that there are two types of classes: 1) the semi-stable classes and
2) the unstable classes. In the first category I count classes like
'Matrix' and 'RowVector'. These haven't seen that many user-visible
changes for a while and are for all practical purposes API stable. In
the second category I count those for interacting with the interpreter
and all sorts of other stuff. These change all the time.

I think we could document the 'semi-stable' classes fairly detailed,
including examples of usage etc. Having the documentation might force us
into trying to actually have a stable API. The 'unstable' classes would,
however, be a pain to document (assuming we would also have to keep the
documentation up to date). I guess we could have very simplistic
documentation for these classes that simply states the overall purpose
of the class.

Just my two cents
Søren