[Python-Dev] Breaking undocumented API

[Ben Finney]

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.

-- 
 \     “I wish there was a knob on the TV to turn up the intelligence. |
  `\          There's a knob called ‘brightness’ but it doesn't work.” |
_o__)                                             —Eugene P. Gallagher |
Ben Finney