[Doc-SIG] PEP 257

[Paul Graves-DesLauriers]

I would like clarification about the one-line docstring
<https://www.python.org/dev/peps/pep-0257/#id16>  example.

 

The Notes say (fourth bullet):

The docstring is a phrase ending in a period. It prescribes the function or
method's effect as a command ("Do this", "Return that"), not as a
description; e.g. don't write "Returns the pathname ...".

 

However the docstring example for kos_root() is:  """Return the pathname of
the KOS root directory."""

 

I've highlighted the areas that seem to contradict each other.  Perhaps the
example should be updated to conform to the notes?

 

Thanks,

Paul

 

 

 

 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mail.python.org/pipermail/doc-sig/attachments/20201229/e290c616/attachment.html>