Issue 15865: reflect bare star * in function signature documentation

This issue is to make sure that the bare * in the function signatures of pure Python functions is properly reflected in the documentation.

This will bring the signatures in the documentation closer to the signatures that we have in the Python code -- a goal articulated by Ezio in a comment to issue 15831.

For example, configparser.RawConfigParser() has this function signature:

def __init__(self, defaults=None, dict_type=_default_dict,
             allow_no_value=False, *, delimiters=('=', ':'),
             comment_prefixes=('#', ';'), inline_comment_prefixes=None,
             strict=True, empty_lines_in_values=True,
             default_section=DEFAULTSECT,
             interpolation=_UNSET):

But its documentation has no *:

class configparser.RawConfigParser(defaults=None, dict_type=collections.OrderedDict, allow_no_value=False, delimiters=('=', ':'), comment_prefixes=('#', ';'), inline_comment_prefixes=None, strict=True, empty_lines_in_values=True, default_section=configaparser.DEFAULTSECT, interpolation=None)

(from http://docs.python.org/dev/library/configparser.html#configparser.RawConfigParser )

From a search of the code, there are about 60 occurrences of a bare * in the signature of a pure Python function (not all of which will need to be updated).

So is the root problem that Sphinx does not handle keyword-only arguments?

> So is the root problem that Sphinx does not handle keyword-only arguments?

I don't think so.  Sphinx renders the * just fine.  It's just that in some of the reST files, the * was left out.

Actually, it looks like configparser is the *only* file with missing single *'s. :)  However, I did find a few other typos in the process of checking those signatures in the other files.

Patch attached.

By looking at x.py, I confirmed that the added stars are correct.
Also, the correction of 'header' to 'hdr' is correct.

However, for threading.py in 3.3.0, I see

class Thread:
...
    def __init__(self, group=None, target=None, name=None,
                 args=(), kwargs=None, *, daemon=None):

whereas the patch and existing .rst

-.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={},
+.. class:: Thread(group=None, target=None, name=None, args=(), kwargs={}, \
                   verbose=None, *, daemon=None)

has an extra 'verbose=None' that should be removed there and in any explanatory text that follows.

(The fact that we found 2 doc signature errors other than the 4 missing *s suggests that we need a tool to systematically compare doc signature to code signature.)

Thanks, Terry.  If anyone is curious, it looks like the verbose keyword argument was added to the docs (and to threading.py) in revision f71acc4b2341, and then subsequently removed (but not from the docs) in revision 8ec51b2e57c2.

> (The fact that we found 2 doc signature errors other than the 4 missing *s suggests that we need a tool to systematically compare doc signature to code signature.)

Out of curiosity, can anyone summarize what our existing tooling might already be able to do in this regard (e.g. Sphinx or pydoc)?

I will update the patch.

Here is an updated patch that incorporates Terry's suggestion.

New changeset a30b3915228b by Ezio Melotti in branch '3.2':
#15865: add "*" in the signature to document keyword-only args in the docs.  Patch by Chris Jerdonek.
http://hg.python.org/cpython/rev/a30b3915228b

New changeset 694c725f241a by Ezio Melotti in branch 'default':
#15865: merge with 3.2.
http://hg.python.org/cpython/rev/694c725f241a

Fixed, thanks for the patch!

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: patch review -> resolved

messages: + msg170020

stage: needs patch