On Tue, Nov 09, 2010 at 11:46:59AM +1100, Ben Finney wrote: > Ron Adam <r...@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. > Just wanted to expand a bit here: as a general practice, you may be involved in a project where the _private_api() is not intended by people outside of the project but is intended to be used in multiple places within the project. If you have different people working on those different areas, it can be very useful for them to be able to use help(_private_api) on the other functions from within the interpreter shell.
-Toshio
pgpG39YJbm42M.pgp
Description: PGP signature
_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
