Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[doc] xxlimited/xxmodule docstrings ambiguous #60935

Open
danielsh mannequin opened this issue Dec 19, 2012 · 6 comments
Open

[doc] xxlimited/xxmodule docstrings ambiguous #60935

danielsh mannequin opened this issue Dec 19, 2012 · 6 comments
Labels
3.11 only security fixes docs Documentation in the Doc dir extension-modules C modules in the Modules dir type-feature A feature request or enhancement

Comments

@danielsh
Copy link
Mannequin

danielsh mannequin commented Dec 19, 2012

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:

    assignee = None
closed_at = None
created_at = <Date 2012-12-19.19:50:46.533>
labels = ['extension-modules', '3.11', 'type-feature', 'docs']
title = '[doc] xxlimited/xxmodule docstrings ambiguous'
updated_at = <Date 2021-09-04.18:30:08.811>
user = 'https://bugs.python.org/danielsh'

    bugs.python.org fields:

    activity = <Date 2021-09-04.18:30:08.811>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Extension Modules']
creation = <Date 2012-12-19.19:50:46.533>
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']
    @danielsh
    Copy link
    Mannequin Author

    danielsh mannequin commented Dec 19, 2012

    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.

    @danielsh danielsh mannequin assigned docspython Dec 19, 2012
    @danielsh danielsh mannequin added docs Documentation in the Doc dir extension-modules C modules in the Modules dir labels Dec 19, 2012
    @danielsh
    Copy link
    Mannequin Author

    danielsh mannequin commented Dec 21, 2012

    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)

    @Winterflower
    Copy link
    Mannequin

    Winterflower mannequin commented Dec 28, 2015

    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?

    @danielsh
    Copy link
    Mannequin Author

    danielsh mannequin commented Dec 30, 2015

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

    @Winterflower
    Copy link
    Mannequin

    Winterflower mannequin commented Jan 1, 2016

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

    @berkerpeksag
    Copy link
    Member

    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.

    @berkerpeksag berkerpeksag added the type-feature A feature request or enhancement label Jan 28, 2016
    @iritkatriel iritkatriel added the 3.11 only security fixes label Sep 4, 2021
    @iritkatriel iritkatriel changed the title xxlimited/xxmodule docstrings ambiguous [doc] xxlimited/xxmodule docstrings ambiguous Sep 4, 2021
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Assignees
    No one assigned
    Labels
    3.11 only security fixes docs Documentation in the Doc dir extension-modules C modules in the Modules dir type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    2 participants
    @berkerpeksag @iritkatriel