On Thu, Jun 27, 2013 at 10:20 AM, Guido van Rossum <guido@python.org> wrote:
On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou <solipsis@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 class _ErrorHolder(object):
251 """
252 Placeholder for a TestCase inside a result. As far as a TestResult
253 is concerned, this looks exactly like a unit test. Used to insert
254 arbitrary errors into a test suite run.
255 """
http://hg.python.org/cpython/file/44f455e6163d/Lib/unittest/suite.py#l250

81 class TestProgram(object):
82 """A command-line program that runs a set of tests; this is primarily
83 for making test modules conveniently executable.
84 """

109 @failfast
110 def addError(self, test, err):
111 """Called when an error has occurred. 'err' is a tuple of values as
112 returned by sys.exc_info().
113 """
114 self.errors.append((test, self._exc_info_to_string(err, test)))
115 self._mirrorOutput = True
117 @failfast
118 def addFailure(self, test, err):
119 """Called when an error has occurred. 'err' is a tuple of values as
120 returned by sys.exc_info()."""
121 self.failures.append((test, self._exc_info_to_string(err, test)))
122 self._mirrorOutput = True
124 @failfast
125 def addSubTest(self, test, subtest, err):
126 """Called at the end of a subtest.
127 'err' is None if the subtest ended successfully, otherwise it's a
128 tuple of values as returned by sys.exc_info().
129 """

589 def do_break(self, arg, temporary = 0):
590 """b(reak) [ ([filename:]lineno | function) [, condition] ]
591 Without argument, list all breaks.