[issue15865] reflect bare star * in function signature documentation

[Ezio Melotti]

Ezio Melotti added the comment:

Fixed, thanks for the patch!

--
assignee: docs@python -> ezio.melotti
resolution:  -> fixed
stage: patch review -> committed/rejected
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Roundup Robot]

Roundup Robot added the comment:

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

--
nosy: +python-dev

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Chris Jerdonek]

Chris Jerdonek added the comment:

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

--
Added file: http://bugs.python.org/file27145/issue-15865-2.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Chris Jerdonek]

Chris Jerdonek added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Terry J. Reedy]

Terry J. Reedy added the comment:

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.)

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Chris Jerdonek]

Changes by Chris Jerdonek :


--
keywords: +needs review
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Chris Jerdonek]

Chris Jerdonek added the comment:

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.

--
keywords: +patch
Added file: http://bugs.python.org/file27124/issue-15865-1.patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Chris Jerdonek]

Chris Jerdonek added the comment:

> 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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Éric Araujo]

Éric Araujo added the comment:

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

--
versions: +Python 3.2

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Ezio Melotti]

Changes by Ezio Melotti :


--
nosy: +eric.araujo, georg.brandl
stage:  -> needs patch

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue15865] reflect bare star * in function signature documentation

[Chris Jerdonek]

New submission from Chris Jerdonek:

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).

--
assignee: docs@python
components: Documentation
keywords: easy
messages: 169850
nosy: cjerdonek, docs@python, ezio.melotti
priority: normal
severity: normal
status: open
title: reflect bare star * in function signature documentation
type: behavior
versions: Python 3.3

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com