Author rhettinger
Recipients docs@python, eimista, eric.smith, rhettinger, yselivanov
Date 2015-05-31.16:49:53
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1433090993.3.0.243753836951.issue24323@psf.upfronthosting.co.za>
In-reply-to
Content
There isn't much defense against an overly literal reading of the docs.  Both ``s.pop([i])`` and ``s.pop(i=-1)`` fail (the latter because pop doesn't take key word arguments and the docstring calls it "index".  Also, you would have to define *s* and *i*. 

FWIW, there is already a note to the effect, "The optional argument i defaults to -1, so that by default the last item is removed and returned."

The [optional_arg] notation is used in a number of places in the docs and docstrings.  It is also common with other languages as well and it is used in third-party Python references as well.  Eric's initial suggestion of ``s.pop(i)`` is simply wrong and would make the docs worse.

As a starting point, realize that the docs have worked well for a lot of people for a long time so there should be a reluctance to change them on a single misreading.

The tutorial also includes the same notation, (see https://docs.python.org/3/tutorial/datastructures.html#more-on-lists ) and as far as I can tell, this has never been an issue.

One other thought, the most common way to call pop() is without an argument (usually, if you use an argument, it is a performance bug).  We want to make sure the docs don't suggest otherwise.

Unless there is some strong objection, I recommend leaving the docs as-is.
History
Date User Action Args
2015-05-31 16:49:53rhettingersetrecipients: + rhettinger, eric.smith, docs@python, yselivanov, eimista
2015-05-31 16:49:53rhettingersetmessageid: <1433090993.3.0.243753836951.issue24323@psf.upfronthosting.co.za>
2015-05-31 16:49:53rhettingerlinkissue24323 messages
2015-05-31 16:49:53rhettingercreate