[issue16731] xxlimited/xxmodule docstrings ambiguous
New submission from Daniel Shahaf: 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. ---------- assignee: docs@python components: Documentation, Extension Modules files: xxdocstrings.diff keywords: patch messages: 177774 nosy: danielsh, docs@python priority: normal severity: normal status: open title: xxlimited/xxmodule docstrings ambiguous versions: Python 3.4 Added file: http://bugs.python.org/file28367/xxdocstrings.diff _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
Daniel Shahaf added the comment: 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) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- nosy: +eric.araujo, loewis _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
Changes by Andrew Svetlov <andrew.svetlov@gmail.com>: ---------- nosy: +asvetlov _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
Camilla Montonen added the comment: 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? ---------- nosy: +Winterflower _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
Daniel Shahaf added the comment: I don't mind at all. Go ahead :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
Camilla Montonen added the comment: Changed xxlimited.c to xxmodule.c in the xxlimited.c docstring. ---------- versions: +Python 3.5, Python 3.6 -Python 3.4 Added file: http://bugs.python.org/file41467/issue16731.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
Berker Peksag added the comment: 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. ---------- nosy: +berker.peksag, serhiy.storchaka stage: -> patch review type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16731> _______________________________________
participants (5)
-
Andrew Svetlov -
Berker Peksag
-
Camilla Montonen
-
Daniel Shahaf
-
Éric Araujo