On 9/22/2013 10:04 PM, Guido van Rossum wrote:
If I had the final word, I'd recommend using the current docstrings as
the .rst contents and replacing the docstrings with the 1-2 line
function descriptions from the PEP, e.g.:
* median(data) -> median (middle value) of data, taking the
average of the two middle values when there are an even
number of values.
But omitting the signature proper, and replacing "->" with "Returns" or
"Returns the". E.g.
def median(data):
"""Returns the median (middle value) of data, taking the
average of the two middle values when there are an even
number of values.
"""
...
I'd personally also rewrite them all so that the first line of the
docstring is a phrase that can stand by itself, as I describe in PEP 8,
but this is used only sporadically in the stdlib.
I am gradually changing Idle docstrings, though only Idle developers
will ever see them. Writing a 60 char summary forces a clear
understanding of the function. Applied to the above.
def median(data):
"""Return the median (middle value) of data.
Use the average of the two middle values when
there are an even number of values.
"""
('Return' rather than 'Returns' is the current convention.)
--
Terry Jan Reedy
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
