classification
Title: reflect bare star * in function signature documentation
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: ezio.melotti Nosy List: chris.jerdonek, docs@python, eric.araujo, ezio.melotti, georg.brandl, python-dev, terry.reedy
Priority: normal Keywords: easy, needs review, patch

Created on 2012-09-05 00:42 by chris.jerdonek, last changed 2012-09-08 17:54 by ezio.melotti. This issue is now closed.

Files
File name Uploaded Description Edit
issue-15865-1.patch chris.jerdonek, 2012-09-05 15:30 review
issue-15865-2.patch chris.jerdonek, 2012-09-08 01:10 review
Messages (9)
msg169850 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-05 00:42
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).
msg169872 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012-09-05 14:49
So is the root problem that Sphinx does not handle keyword-only arguments?
msg169874 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-05 14:58
> 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.
msg169876 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-05 15:30
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.
msg170012 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-09-07 21:07
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.)
msg170013 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-07 21:43
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.
msg170020 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-09-08 01:10
Here is an updated patch that incorporates Terry's suggestion.
msg170060 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2012-09-08 17:53
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
msg170061 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-08 17:54
Fixed, thanks for the patch!
History
Date User Action Args
2012-09-08 17:54:53ezio.melottisetstatus: open -> closed
messages: + msg170061

assignee: docs@python -> ezio.melotti
resolution: fixed
stage: patch review -> resolved
2012-09-08 17:53:10python-devsetnosy: + python-dev
messages: + msg170060
2012-09-08 01:10:53chris.jerdoneksetfiles: + issue-15865-2.patch

messages: + msg170020
2012-09-07 21:43:08chris.jerdoneksetmessages: + msg170013
2012-09-07 21:07:54terry.reedysetnosy: + terry.reedy
messages: + msg170012
2012-09-05 15:38:03chris.jerdoneksetkeywords: + needs review
stage: needs patch -> patch review
2012-09-05 15:30:53chris.jerdoneksetfiles: + issue-15865-1.patch
keywords: + patch
messages: + msg169876
2012-09-05 14:58:46chris.jerdoneksetmessages: + msg169874
2012-09-05 14:49:01eric.araujosetmessages: + msg169872
versions: + Python 3.2
2012-09-05 09:38:58ezio.melottisetnosy: + georg.brandl, eric.araujo

stage: needs patch
2012-09-05 00:42:31chris.jerdonekcreate