Re: Undocumented internal function

[Jaroslav Hajek]

2010/8/31 Jordi Gutiérrez Hermoso <address@hidden>:
> I hope I'm not getting myself into trouble disagreeing with John
> here...

Surely you are. Now you have the holy Octave inquisition after you.
Next time you compile Octave, watch your hard disk :) Hahaha. Come
one.

> 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?
>

I have the sources at hand.

>> 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.
>

The point is that help strings are intended for all users, not just
developers, and users are not expected to use the internal funcs.
Often an internal function is used in just one or several m-funcs, and
the way it's used there is all that the internal function can do.
__accumarray_sum__ or __sort_rows_idx__ are good examples. Why
document them? They implement just a special case of accumarray and
sortrows. In order to use them, you *are* expected to read and
understand the code of the m-function, and their own C++ code. By not
documenting these functions, we discourage regular users from using
them, which is precisely what we want to.

There's still at least one good idea stated above; it would be nice to
have a mapping from builtins to source locations, as a tool in the
source tree. I don't think it needs to ship with the binaries, though.

>> | 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.
>

There are many things about Octave that should be done. When you point
out that something should be done, consider the possibility that
others are already aware of it. But *who* is going to do it, and
*how*, that is usually a much harder problem.

To the point: I wouldn't object to doxygenizing the sources. Just be
careful that there is still a lot of macro trickery around - is that
handled well by Doxygen? But as far as I'm concerned, if you start it
and carry on far enough, then at one point I (and probably others as
well) will start to follow. It's as easy as that. Or isn't it? :)

-- 
RNDr. Jaroslav Hajek, PhD
computing expert & GNU Octave developer
Aeronautical Research and Test Institute (VZLU)
Prague, Czech Republic
url: www.highegg.matfyz.cz