[Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257) (original) (raw)
Guido van Rossum guido at python.org
Thu Jun 27 03:56:10 CEST 2013
- Previous message: [Python-Dev] PyArg_ParseTupe(): parse unsigned integer and check for overflow
- Next message: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]
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.
-- --Guido van Rossum (python.org/~guido)
- Previous message: [Python-Dev] PyArg_ParseTupe(): parse unsigned integer and check for overflow
- Next message: [Python-Dev] Reminder: an oft-forgotten rule about docstring formatting (PEP 257)
- Messages sorted by: [ date ] [ thread ] [ subject ] [ author ]