Terry J. Reedy added the comment:
The large issue is documenting complex signatures that do not really fit in any
of the standard one-line patterns.
I was initially puzzled by Raymond describing the 3.3 line as 'confusing', but
putting on 'newbie glasses' I see now that correctly parsing
int([number | string[, base]])
requires knowing that '[, option]' binds tighter than '|'. Since ',' normally
has the lowest binding priority, someone who does not know the signature
already (ie, a target audience member) could parse it as
int([ (number | string) [, base]])
rather than as intended:
int([number | (string[, base]) ])
So I agree that the two stacked lines in the doc patch are clearer.
However, this issue is about the docstring. Leave it incorrect? Change it to
the hard-to-parse one liner? Change it to a two-line signature also? I noticed
this issue while working on IDLE tooltips, using int as a test case. They
currently use only the first line of the docstring, but I have decided that
they should get more when needed for C functions. (For Python functions,
tooltips use inspect for the actual signature and the first docstring line only
for a description.)
The first line of the str docstring is also incorrect in that the optional
parameters are only valid for first arguments that are strings.
str(string[, encoding[, errors]]) -> str
It needs either a '|' construction like int or another line:
str(object)
I prefer the latter. I revised the title to add str.__doc__ to the issue.
While we are at it, how about
range(stop)
range(start, stop, [step])
instead of the current doc and docstring signature
range([start,] stop[, step])
? The current docstring is inaccurate and confusing to some. (How can there be
an optional first arg and required second ? -- Answer: there can't.) The
technically accurate signature is
range(start_or_stop[, stop[, step]])
but that has been rejected as confusing.
The bytes and bytearrays docstrings have 5 signature lines!. (The manual gives
just one which does not quite cover all cases.) So (a) there is precedent for
multiple signatures in docstrings and (b) tooltips already need to grab
multiple signature lines. So I think int and str (and maybe range) should use a
couple of clear lines.
If the new inspect.signature function were to give signatures for C functions,
there would be no problem for tooltips, but it does not. (Can signature objects
even handle multiple (or type-dependent) signatures?)
----------
nosy: +georg.brandl
title: Update int() docstring from manual -> Make int() and str() docstrings
correct
_______________________________________
Python tracker <rep...@bugs.python.org>
<http://bugs.python.org/issue14783>
_______________________________________
_______________________________________________
Python-bugs-list mailing list
Unsubscribe:
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
