Repository navigation
comma after leading optional argument is after bracket in docs #60035
Description
| BPO | 15831 |
|---|---|
| Nosy | @birkenfeld, @ezio-melotti, @merwok, @asvetlov, @cjerdonek |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = 'https://github.com/ezio-melotti'
closed_at = <Date 2012-09-15.01:47:48.818>
created_at = <Date 2012-08-31.15:57:14.121>
labels = ['easy', 'type-feature', 'docs']
title = 'comma after leading optional argument is after bracket in docs'
updated_at = <Date 2012-09-15.01:47:48.817>
user = 'https://github.com/cjerdonek'bugs.python.org fields:
activity = <Date 2012-09-15.01:47:48.817>
actor = 'ezio.melotti'
assignee = 'ezio.melotti'
closed = True
closed_date = <Date 2012-09-15.01:47:48.818>
closer = 'ezio.melotti'
components = ['Documentation']
creation = <Date 2012-08-31.15:57:14.121>
creator = 'chris.jerdonek'
dependencies = []
files = ['27104', '27120']
hgrepos = []
issue_num = 15831
keywords = ['patch', 'easy', 'needs review']
message_count = 32.0
messages = ['169547', '169549', '169550', '169553', '169555', '169557', '169559', '169561', '169562', '169563', '169565', '169566', '169568', '169647', '169649', '169652', '169696', '169697', '169709', '169726', '169828', '169832', '169836', '169844', '169851', '170471', '170472', '170493', '170495', '170499', '170500', '170501']
nosy_count = 7.0
nosy_names = ['georg.brandl', 'ezio.melotti', 'eric.araujo', 'asvetlov', 'chris.jerdonek', 'docs@python', 'python-dev']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue15831'
versions = ['Python 2.7', 'Python 3.2', 'Python 3.3', 'Python 3.4']
Activity
cjerdonek commentedon Aug 31, 2012
From docs@python.org:
"""
In a number of places we find documentation with optional leading arguments where the meta-notation (square brackets) are in the wrong place. For example, for range, the standard doc heading says
The same error occurs with docs for print, and for slice, for random.randrange and for random.seed, etc, etc. This seems a consistent bug whenever a function or method takes an optional first argument, and it looks like it might have been put there by some tool that generates the docs.
I use Python 3 - perhaps there was once a time when one had to supply the comma if one omitted the first argument? In Python 3 it gives errors if one follows the documentation carefully and uses the comma.
""""
(or see http://mail.python.org/pipermail/docs/2012-August/010051.html )
cjerdonek commentedon Aug 31, 2012
Do we know that this is easy? It might be a Sphinx issue, in which case it might not be as trivial as fixing typos.
I ask because the reST file looks correct (for range() for example):
.. function:: range([start,] stop[, step])
ezio-melotti commentedon Aug 31, 2012
I thought that was just a matter of finding the wrong commas and fixing them, but if they are correct in the source, then the situation might be a bit more complicated.
Does this happen only with "unusual" signatures like range([start], stop [, step])?
FWIW this could be replaced with:
range(stop)
range(start, stop [, step])
cjerdonek commentedon Aug 31, 2012
This is what my search for ",] " gave me (though the OP's print and random.seed do not show up in this list):
library/curses.rst
380:.. function:: newwin([nlines, ncols,] begin_y, begin_x)
659:.. method:: window.addch([y, x,] ch[, attr])
673:.. method:: window.addnstr([y, x,] str, n[, attr])
679:.. method:: window.addstr([y, x,] str[, attr])
766:.. method:: window.chgat([y, x, ] [num,] attr)
815:.. method:: window.derwin([nlines, ncols,] begin_y, begin_x)
909:.. method:: window.hline([y, x,] ch, n)
943:.. method:: window.insch([y, x,] ch[, attr])
964:.. method:: window.insnstr([y, x,] str, n [, attr])
1156:.. method:: window.subpad([nlines, ncols,] begin_y, begin_x)
1162:.. method:: window.subwin([nlines, ncols,] begin_y, begin_x)
1219:.. method:: window.vline([y, x,] ch, n)
library/functions.rst
1064:.. function:: range([start,] stop[, step])
1129:.. function:: slice([start,] stop[, step])
library/itertools.rst
55::func:`islice` seq, [start,] stop [, step] elements from seq[start:stop:step] ``islice('ABCDEFG', 2, None) --> C D E F G``
404:.. function:: islice(iterable, [start,] stop [, step])
library/random.rst
96:.. function:: randrange([start,] stop[, step])
library/syslog.rst
20:.. function:: syslog([priority,] message)
library/tkinter.tix.rst
507:.. method:: tixCommand.tix_configure([cnf,] **kw)
asvetlov commentedon Aug 31, 2012
Yes, it looks like Sphinx problem.
About having tho signatures for single function/method.
Does Sphinx support it for *.. function::*?
Pointing to anchor for first signature with adding second one somewhere in paragraph text doesn't look good.
ezio-melotti commentedon Aug 31, 2012
I'm pretty sure it does for methods, so I don't see why it shouldn't work for functions.
asvetlov commentedon Aug 31, 2012
No, methods for *curses* are also corrupted.
ezio-melotti commentedon Aug 31, 2012
It would be fine with me to use a double signature for these.
Georg, do you have any opinion?
(The double signature might be easier to understand, but the original issue should probably be fixed in Sphinx, even if we decide to stop using this kind of signature.)
ezio-melotti commentedon Aug 31, 2012
I meant the double signature support.
cjerdonek commentedon Aug 31, 2012
Just an FYI that more than two signatures would be needed for cases like this:
766:.. method:: window.chgat([y, x, ] [num,] attr)
ezio-melotti commentedon Aug 31, 2012
What's this even supposed to mean?
See also bpo-14783.
14 remaining items
python-dev commentedon Sep 14, 2012
New changeset b01eb870f84f by Ezio Melotti in branch '3.2':
bpo-15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
http://hg.python.org/cpython/rev/b01eb870f84f
New changeset 0ed61ee823d8 by Ezio Melotti in branch 'default':
bpo-15831: merge with 3.2
http://hg.python.org/cpython/rev/0ed61ee823d8
New changeset 2291aff20a05 by Ezio Melotti in branch '2.7':
bpo-15831: document multiple signatures on different lines. Patch by Chris Jerdonek.
http://hg.python.org/cpython/rev/2291aff20a05
ezio-melotti commentedon Sep 14, 2012
Fixed, thanks for the patch!
cjerdonek commentedon Sep 14, 2012
Thanks, Ezio!
By the way, I didn't do a thorough check, but I noticed this difference in the 2.7 application of the patch. The *key* argument for max() needs to be marked keyword-only. This difference doesn't exist for the min() function. Or are we not using the "bare *" notation in the 2.7 docs? If not, the min() docs need to be changed instead (and possibly in several other places).
Default branch:
-.. function:: max(iterable[, args...], *[, key])
+.. function:: max(iterable, *[, key])
+ max(arg1, arg2, *args[, key])
2.7 branch:
-.. function:: max(iterable[, args...][key])
+.. function:: max(iterable[, key])
+ max(arg1, arg2, *args[, key])
cjerdonek commentedon Sep 14, 2012
Someone pointed out that keyword-only arguments were introduced only in 3.0, but I'm not sure whether that means we can't use them as a notational device in the 2.7 docs.
cjerdonek commentedon Sep 15, 2012
Since the bare * notation wasn't added until 3.0, my guess is that we want to remove the * below (from the 2.7 application of the patch) rather than adding it back in the max() function I pasted above:
-.. function:: min(iterable[, args...][key])
+.. function:: min(iterable, *[, key])
+ min(arg1, arg2, *args[, key])
python-dev commentedon Sep 15, 2012
New changeset 881acdf9133f by Ezio Melotti in branch '2.7':
bpo-15831: avoid using 3.x syntax for keyword-only args.
http://hg.python.org/cpython/rev/881acdf9133f
ezio-melotti commentedon Sep 15, 2012
The * is not supposed to be used on 2.7, but I missed that.
Thanks for noticing!