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 <report@bugs.python.org> <http://bugs.python.org/issue14783> _______________________________________