[docs] [issue18220] Expand itertools.islice docstring signature to 2 lines

[Terry J. Reedy]

Terry J. Reedy added the comment:

The problem with all of range, slice, and islice is that 
[start,] stop [, step] is an impossible signature and needed to be changed.

The actual signature is
start_or_stop, [stop, [step]]
with customized processing to interpret start_or_stop according to the presence of stop (which is not really optional). We suggestion to doc it this was rejected as equally confusing.

In 3.3, we decided to stop trying to force all signatures presented to the user into one line and instead use multiple lines to present what are multiple signatures from a user view. So this alternative was used for range and slice (and other functions).

For islice, the islice entry has
itertools.islice(iterable, stop)
itertools.islice(iterable, start, stop[, step])

Py.user is corrrect in suggesting the same change for islice docstring. I have changed the title to be clearer.

The itertools function table has
islice() 	seq, [start,] stop [, step] 	elements from ...

I thing this should be changed also. A new line for arguments 'seq, stop' would say
'elements from seq[0:stop]'   example 'islice('ABCDEFG', 2) --> A B
Then remove brackets from [start] in the current line.

Py.user: To accept non-trival patches (typos, grammar corrections are trivial) we need a signed contributor agreement
http://www.python.org/psf/contrib/  and
http://www.python.org/psf/contrib/contrib-form/  new electronic form
An '*' will appear after your name here when it is processed.
I presume this will need a real (legal) name on the form, even though not in the tracker user list.

----------
nosy: +terry.reedy
stage:  -> patch review
title: In itertools.islice() make prototype like in help() -> Expand itertools.islice docstring signature to 2 lines

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue18220>
_______________________________________