Re: Undocumented internal function

[Søren Hauberg]

tir, 31 08 2010 kl. 16:21 -0500, skrev Jordi Gutiérrez Hermoso:
> 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?

By documenting these functions we are encouraging people to use it. In
general people just don't seem to care if the function is internal or
not, and then they start complaining when we change the API of these
functions.

Also, internal functions are more prone to changes meaning that we have
to keep the documentation up to date every time an internal function
changes. This is just bound to cause problems.

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

Comeon, if you're going to hack on internal stuff you should be abe to
type 'source __internal_function__' :-)

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

We could probably pick a few classes ('Matrix'??) and declare those
semi-stable. These could then be documented. However, we should probably
start by figuring out which parts of the API should be stable before
even considering documenting them. My main concern is that it will take
the fun out of hacking if documentation has to be updated every time
something internal changes.

Soren