On 24-Jan-2011, Jordi Gutiérrez Hermoso wrote:
| 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".
If you are complaining again about things like the public docstrings
which say "Undocumented internal function", then I think you are
missing the point of that message, and that issue is completely
separate from whether we start to document liboctave classses with
Doxygen.
As I think we've discussed before, the functions that have
"Undocumented internal function" docstrings are intended to be private
internal functions that should not be called except by other parts of
Octave. If we could somehow make them private (like private functions
in a C++ class) we would, but namespace management in the "Matlab
language" is not so good, and there are good reasons not to try to add
more band-aids to an already iffy language design. In some cases,
these functions are documented with comments in the source files, so
if someone needs to understand what they do in order to fix a bug in
Octave, then can look there. But I don't think there is any point in
having the user-level help system display that information and
encourage people to call functions that they should not be using
directly.
jwe