[docs] [issue12875] backport re.compile flags default value documentation

[Eli Bendersky]

Eli Bendersky <eliben at gmail.com> added the comment:

Amaury & Georg,

Grepping through the docs disagrees with your claims ;-) Try to grep for "\=None\]" to see what I mean. There are tons of places where default values are placed inside the brackets. For example in http://docs.python.org/library/csv.html --> look at:

    sniff(sample[, delimiters=None])

or even:

    class csv.DictReader(csvfile[, fieldnames=None[, restkey=None[, restval=None[, dialect='excel'[, *args, **kwds]]]]])

That said, I have absolutely no objections to following an accepted convention. But what is it?

I looked around, and found the following in the documentation guide:

http://docs.python.org/dev/py3k/documenting/fromlatex.html

    There is no optional command. Just give function signatures 
    like they should appear in the output:

    .. function:: open(filename[, mode[, buffering]])

       Description.

This (taken from the 3.3 guide) mentions the 2.x guideline and doesn't mention default values.

So what should I do here? According to Ezio's earlier message, the new style (without brackets) is also being used in Python 2 now. I can do the switch for the 're' module, but can we first get the convention documented somewhere?

----------

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