Re: Undocumented internal function

[Jordi Gutiérrez Hermoso]

I hope I'm not getting myself into trouble disagreeing with John
here... Perhaps there's something more important I'm not seeing at a
first glance.

Nevertheless, I must disagree, at least for now:

2010/8/31 John W. Eaton <address@hidden>:
> On 31-Aug-2010, Jordi Gutiérrez Hermoso wrote:
>
> | This phrase is a little silly. It's ok if functions are internal, but
> | that's no excuse to not document them, even if briefly. Can we
> | deprecate this practice?
>
> No.

Why not? It's handy. When I want to find where something happens in
the code, the first thing I do is think of what I would type in the
interpreter to make that happen. Then I look at the help for that
command, which tells me where it's defined. That at least gives me a
first clue of what's getting called and how. And if it had a little
tidbit about what it's supposed to do, it would be even better.

What do you do instead if you want to modify something about Octave
you're not familiar with or have forgotten?

> Actually, there can be documentation for the internal functions in
> the form of comments in the code, but I don't think it should be
> printed by the help function.

In that case, it wouldn't be "undocumented" at all and the phrase is
still silly. The help function could point to the source file. In the
case of m-script functions, this already happens. Perhaps with C macro
magic, the help function could also know in which source files a DLD
or built-in function is defined. Furthermore, I doubt internal
documentation in source code will happen unless there's some sort of
actual coercing by the API (e.g. the DEFUN macro requires a docstring)
or a policy like the one there is for ChangeLogs and GNU coding
standards right now.

> | I also have grand dreams of using Doxygen to actually document the
> | C++ API, but I'm not sure how that would fit in with all the
> | TeXinfo already in place.
>
> What API?

The one that many people use to make their own oct files. Sure, it's
never been stabilised, and API compatibility has never been a goal,
and it would be a huge chore to document what is there, but despite
all this, it should be done. Octave-Forge publishes the current
bare-bones Doxygen output of the Octave API, which albeit not entirely
useless, is is not much better than reading the source itself.

- Jordi G. H.