classification
Title: xxlimited/xxmodule docstrings ambiguous
Type: enhancement Stage: patch review
Components: Documentation, Extension Modules Versions: Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Winterflower, asvetlov, berker.peksag, danielsh, docs@python, eric.araujo, loewis, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2012-12-19 19:50 by danielsh, last changed 2016-01-28 10:53 by berker.peksag.

Files
File name Uploaded Description Edit
xxdocstrings.diff danielsh, 2012-12-19 19:50 review
issue16731.patch Winterflower, 2016-01-01 21:00 review
Messages (6)
msg177774 - (view) Author: Daniel Shahaf (danielsh) Date: 2012-12-19 19:50
Tweak the docstrings of xxmodule and xxlimited to clarify the difference between them (as derived from setup.py).  While at it also add a defensive coding guard to xxlimited to ensure it remains Py_LIMITED_API-safe.
msg177880 - (view) Author: Daniel Shahaf (danielsh) Date: 2012-12-21 16:03
Re the review, yes there is a typo in the comment: the comment in xxlimited.c should say "xxmodule.c" rather than "xxlimited.c".  (Got a traceback from the review app)
msg257127 - (view) Author: Camilla Montonen (Winterflower) Date: 2015-12-28 19:52
Hi Daniel, 
just about to review this patch and noticed that the typo in xxlimited.c docstring is still there. Do you mind if I tweak your patch to fix this?
msg257231 - (view) Author: Daniel Shahaf (danielsh) Date: 2015-12-30 10:26
I don't mind at all.  Go ahead :)
msg257301 - (view) Author: Camilla Montonen (Winterflower) Date: 2016-01-01 21:00
Changed xxlimited.c to xxmodule.c in the xxlimited.c docstring.
msg259123 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-01-28 10:53
I think the difference between xxlimited and xxmodule is still a bit ambiguous. I would expect a mention of PEP 384 or a link to https://docs.python.org/3/c-api/stable.html to explain what Py_LIMITED_API really is.

+#ifndef Py_LIMITED_API
+# error "This file requires Py_LIMITED_API"
+#endif

I don't have a strong opinion about this, but I think the error message could be more informative (e.g. you must define a Py_LIMITED_API macro) Or we can improve https://docs.python.org/3/c-api/stable.html to give an example there.
History
Date User Action Args
2016-01-28 10:53:22berker.peksagsetnosy: + serhiy.storchaka, berker.peksag
messages: + msg259123

type: enhancement
stage: patch review
2016-01-01 21:00:18Winterflowersetfiles: + issue16731.patch

messages: + msg257301
versions: + Python 3.5, Python 3.6, - Python 3.4
2015-12-30 10:26:07danielshsetmessages: + msg257231
2015-12-28 19:52:09Winterflowersetnosy: + Winterflower
messages: + msg257127
2012-12-30 00:12:11asvetlovsetnosy: + asvetlov
2012-12-21 17:17:09eric.araujosetnosy: + loewis, eric.araujo
2012-12-21 16:03:07danielshsetmessages: + msg177880
2012-12-19 19:50:46danielshcreate