Skip Montanaro 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

On Thu, Jun 27, 2013 at 1:21 AM, Antoine Pitrou wrote:

I don't always find it easy to summarize a function in one line.

Neither do I. But I always manage to do it anyway. My reasoning is, you can always leave out more detail and add it to the subsequent paragraph. -- --Guido van Rossum (python.org/~guido)

Antoine Pitrou writes:

I don't always find it easy to summarize a function in one line.

Difficulty in coming up with an accurate one-line summary of the intent of a function is a code smell: the function probably needs to be simplified so it is easier to describe accurately. This is, IMO, one of the primary benefits of having a convention of expecting a one-line summary for every function (and module and class). -- \ “Courage is not the absence of fear, but the decision that | `\ something else is more important than fear.” —Ambrose Redmoon | _o__) | Ben Finney

Yes on one line, capitalized, period. No on single sentence. --Guido van Rossum (sent from Android phone) On Jun 27, 2013 8:17 AM, "Larry Hastings" wrote:

On 06/26/2013 08:56 PM, Guido van Rossum wrote:

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.

Argument Clinic could conceivably enforce this. It could mandate that the first paragraph of the function docstring contain exactly one sentence (must end in a period, all embedded periods cannot be followed by whitespace). This would make some things nicer; I could automatically insert the per-parameter docstrings in after the summary.

Should it?

*/arry*

_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/guido%40python.org

It was never my intention to enforce that everything has a docstring. Just that if it does, it looks good. On Thu, Jun 27, 2013 at 9:40 AM, Terry Reedy wrote:

On 6/27/2013 11:57 AM, Guido van Rossum wrote:

...

Yes on one line, capitalized, period. No on single sentence.

Complete and correct docstrings are somewhat rare in idlelib. About half are missing. Single lines typically omit the period. Multiple lines often omit the blank line after the first.

I will take your reminder as permission to make changes as I review the code. I wish there were more good summary lines already.

My understanding is that SubclassTests and test_methods should not have docstrings.

-- Terry Jan Reedy

_______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/guido%40python.org

-- --Guido van Rossum (python.org/~guido)

Terry Reedy writes:

Ok, I won't add them when a function's name actually makes what it does obvious. But when I have to spend at least a few minutes reading the body to make sense of it, I will try to add the summary line that I wish had been there already.

+1 That's a *great* rule-of-thumb!