[Python-Dev] Breaking undocumented API

[Guido van Rossum]

On Mon, Nov 8, 2010 at 4:46 PM, Ben Finney <ben+python at benfinney.id.au> wrote:
> Ron Adam <rrr at ronadam.com> writes:
>
>> def _publicly_documented_private_api():
>>     """  Not sure why you would want to do this
>>          instead of using comments.
>>     """
>>     ...
>
> Because the docstring is available at the interpreter via ‘help()’, and
> because it's automatically available to ‘doctest’, and most of the other
> good reasons for docstrings.
>
>> The _publicly_documented_private_api() is a problem because people
>> *will* use it even though it has a leading underscore. Especially
>> those who are new to python.
>
> That isn't an argument against docstrings, since the problem you
> describe isn't dependent on the presence or absence of docstrings.

+1

-- 
--Guido van Rossum (python.org/~guido)