search

python / cpython

The Python programming language
https://www.python.org
Other
63.68k stars 30.51k forks source link

[doc] xxlimited/xxmodule docstrings ambiguous #60935

Open af633b44-561a-4b52-8b63-c956c603afaf opened 11 years ago

af633b44-561a-4b52-8b63-c956c603afaf commented 11 years ago
BPO 16731
Nosy @loewis, @merwok, @asvetlov, @berkerpeksag, @serhiy-storchaka
Files
  • xxdocstrings.diff
  • issue16731.patch
    		•

    Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields: ```python assignee = None closed_at = None created_at = labels = ['extension-modules', '3.11', 'type-feature', 'docs'] title = '[doc] xxlimited/xxmodule docstrings ambiguous' updated_at = user = 'https://bugs.python.org/danielsh' ``` bugs.python.org fields: ```python activity = actor = 'iritkatriel' assignee = 'docs@python' closed = False closed_date = None closer = None components = ['Documentation', 'Extension Modules'] creation = creator = 'danielsh' dependencies = [] files = ['28367', '41467'] hgrepos = [] issue_num = 16731 keywords = ['patch'] message_count = 6.0 messages = ['177774', '177880', '257127', '257231', '257301', '259123'] nosy_count = 8.0 nosy_names = ['loewis', 'eric.araujo', 'asvetlov', 'docs@python', 'berker.peksag', 'serhiy.storchaka', 'danielsh', 'Winterflower'] pr_nums = [] priority = 'normal' resolution = None stage = 'patch review' status = 'open' superseder = None type = 'enhancement' url = 'https://bugs.python.org/issue16731' versions = ['Python 3.11'] ```

    af633b44-561a-4b52-8b63-c956c603afaf commented 11 years ago

    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.

    af633b44-561a-4b52-8b63-c956c603afaf commented 11 years ago

    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)

    913479bb-37e6-4dd5-9d09-bfa0704c65f0 commented 8 years ago

    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?

    af633b44-561a-4b52-8b63-c956c603afaf commented 8 years ago

    I don't mind at all. Go ahead :)

    913479bb-37e6-4dd5-9d09-bfa0704c65f0 commented 8 years ago

    Changed xxlimited.c to xxmodule.c in the xxlimited.c docstring.

    berkerpeksag commented 8 years ago

    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.