Yes on one line, capitalized, period. No on single sentence. --Guido van Rossum (sent from Android phone) On Jun 27, 2013 8:17 AM, "Larry Hastings" <la...@hastings.org> wrote:
> On 06/26/2013 08:56 PM, Guido van Rossum wrote: > > PEP 257 says this on the formatting of multi-line docstrings: > > """ > Multi-line docstrings consist of a summary line just like a one-line > docstring, followed by a blank line, followed by a more elaborate > description. The summary line may be used by automatic indexing tools; > it is important that it fits on one line and is separated from the > rest of the docstring by a blank line. [...] > """ > > I still like this rule, but it is violated frequently, in the stdlib > and elsewhere. I'd like to urge stdlib contributors and core devs to > heed it -- or explain why you can't. > > > Argument Clinic could conceivably enforce this. It could mandate that the > first paragraph of the function docstring contain exactly one sentence > (must end in a period, all embedded periods cannot be followed by > whitespace). This would make some things nicer; I could automatically > insert the per-parameter docstrings in after the summary. > > Should it? > > > */arry* > > _______________________________________________ > 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/guido%40python.org > >
_______________________________________________ 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
