[Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)

[Alexander Belopolsky]

On Thu, Jun 27, 2013 at 10:20 AM, Guido van Rossum <guido at python.org> wrote:

> On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou <solipsis at pitrou.net>
> wrote:
> > I don't always find it easy to summarize a function in one line.
>
> Neither do I. But I always manage to do it anyway.


+1

If you cannot summarize what your function does in one line, chances are it
is time to split your function, not the summary line.  Ideally, the name of
the function should already give a good idea of what it does.  A summary
line can just rephrase the same in a complete sentence.

I took a quick look at the stdlib and in many cases a summary line is
already there.  It is just the issue of formatting.

 250<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250>
class _ErrorHolder(object):
251<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l251>
"""
252<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l252>
Placeholder
for a TestCase inside a result. As far as a TestResult
253<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l253>
is
concerned, this looks exactly like a unit test. Used to insert
254<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l254>
arbitrary
errors into a test suite run.
255<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l255>
"""
*http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250*

81 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81>
class TestProgram(object):
82 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l82>
"""A
command-line program that runs a set of tests; this is primarily
83 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l83>
for
making test modules conveniently executable.
84 <http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l84>
"""
*http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/main.py#l81*

109<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109>
@failfast
110<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l110>
def addError(self, test, err):
111<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l111>
"""Called
when an error has occurred. 'err' is a tuple of values as
112<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l112>
returned
by sys.exc_info().
113<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l113>
"""
114<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l114>
self.errors.append((test, self._exc_info_to_string(err, test)))
115<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l115>
self._mirrorOutput = True
116<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l116>
117<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l117>
@failfast
118<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l118>
def addFailure(self, test, err):
119<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l119>
"""Called
when an error has occurred. 'err' is a tuple of values as
120<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l120>
returned
by sys.exc_info()."""
121<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l121>
self.failures.append((test, self._exc_info_to_string(err, test)))
122<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l122>
self._mirrorOutput = True
123<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l123>
124<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l124>
@failfast
125<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l125>
def addSubTest(self, test, subtest, err):
126<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l126>
"""Called
at the end of a subtest.
127<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l127>
'err'
is None if the subtest ended successfully, otherwise it's a
128<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l128>
tuple
of values as returned by sys.exc_info().
129<http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l129>
"""
*http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/result.py#l109*
*
*
589 <http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589> def
do_break(self, arg, temporary = 0):
590 <http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l590> """b(reak)
[ ([filename:]lineno | function) [, condition] ]
591 <http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l591> Without
argument, list all breaks.
*http://hg.python.org/cpython/file/44f455e6163d/Lib/pdb.py#l589*
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20130627/e14af801/attachment-0001.html>