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.)