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

Ben Finney ben+python at benfinney.id.au
Thu Jun 27 07:29:00 CEST 2013

Skip Montanaro <skip at pobox.com> writes:

Where I can [conform to PEP 257], I do, however I often find it difficult to come up with a one-liner, especially one that mentions the parameters to functions.

I think it's far better to make the synopsis a summary of the purpose of the function; no need to force the parameters in there if they don't fit naturally in the sentence fragment.

A list of the parameters and return value can go in the detailed description.

-- \ “Theology is the effort to explain the unknowable in terms of | `\ the not worth knowing.” —Henry L. Mencken | o_) | Ben Finney

More information about the Python-Dev mailing list