Re: Undocumented internal function

[Jordi Gutiérrez Hermoso]

2010/9/1 Soren Hauberg <address@hidden>:
> By documenting these functions we are encouraging people to use it.

This, this is *precisely* the attitude that I want to deprecate. That
it's desirable and good to consciously choose to not document
functions and that we'd be doing some sort of damage if we document
them, that users need to be consciously herded for their own good.
It's a paternalistic attitude, that users are too dumb and we need to
steer them by not documenting functions.

I say, if a user has been curious enough to find the internal
functions, which they may well have found by reading source code where
they're called, we should *reward* that behaviour by telling them what
the function is (and prominently mark it as internal, in case they
wandered there by mistake).

This attitude is disrespectful to users. Treat all of your users as
potential developers and peers, not as a flock of sheep that needs to
be herded.