Re: TexInfo -> Doxygen

[Jordi Gutiérrez Hermoso]

2011/1/24 John W. Eaton <address@hidden>:
> 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.

Then why call then "undocumented"? If we're talking about encouraging
people or not, that name seems to be encouraging just that:
undocumentation. I just grepped the source code for "undocumented
internal", and there are 61 hits under src/, and of those, I found
about 25 of them with comments documenting what they were doing.
Actually, given the usual sparseness of documentation, I guess that
isn't so bad. The problem is that the string appears precisely as a
placeholder where careful documentation for functions normally goes,
so it does seem to be promoting undocumentation.

Anyways, you're right that this is quite besides the point of what
Doxygen can do or should be used for. I'll prepare patches to
exemplify Doxygen and then we can decide if this is a good idea or
not.

- Jordi G. H.