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.

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

Fix incorrect use of directives in asyncio documentation #90933

Closed
serhiy-storchaka opened this issue Feb 17, 2022 · 5 comments
Closed

Fix incorrect use of directives in asyncio documentation #90933

serhiy-storchaka opened this issue Feb 17, 2022 · 5 comments
Labels
3.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir topic-asyncio type-feature A feature request or enhancement

Comments

@serhiy-storchaka
Copy link
Member

BPO 46777
Nosy @gvanrossum, @asvetlov, @serhiy-storchaka, @1st1, @miss-islington, @Fidget-Spinner
PRs
  • bpo-46777: Fix incorrect use of directives in asyncio documentation #31388
  • [3.10] bpo-46777: Fix incorrect use of directives in asyncio documentation (GH-31388) #31403
    		•

    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 = <Date 2022-02-19.08:09:43.047>
created_at = <Date 2022-02-17.12:54:16.588>
labels = ['3.11', 'type-feature', 'docs', '3.10', 'expert-asyncio']
title = 'Fix incorrect use of directives in asyncio documentation'
updated_at = <Date 2022-02-26.16:13:00.374>
user = 'https://github.com/serhiy-storchaka'

    bugs.python.org fields:

    activity = <Date 2022-02-26.16:13:00.374>
actor = 'gvanrossum'
assignee = 'docs@python'
closed = True
closed_date = <Date 2022-02-19.08:09:43.047>
closer = 'serhiy.storchaka'
components = ['Documentation', 'asyncio']
creation = <Date 2022-02-17.12:54:16.588>
creator = 'serhiy.storchaka'
dependencies = []
files = []
hgrepos = []
issue_num = 46777
keywords = ['patch']
message_count = 5.0
messages = ['413404', '413408', '413469', '413470', '413474']
nosy_count = 7.0
nosy_names = ['gvanrossum', 'asvetlov', 'docs@python', 'serhiy.storchaka', 'yselivanov', 'miss-islington', 'kj']
pr_nums = ['31388', '31403']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue46777'
versions = ['Python 3.10', 'Python 3.11']
    @serhiy-storchaka
    Copy link
    Member Author

    There are some issues with formatting added or removed parameters in the asyncio module.

    1. "deprecated-removed" directives were used for already removed directives. It should be used for deprecated features with known term of removal. For removed features "versionchanged" is more appropriate.

    2. Text for removed parameters was too verbose. "Removed the XXX parameter" would be enough.

    3. "versionadded" directives were used for new parameters. "versionchanged" directive is more appropriate. It is a date of the change in existing function, not the date of adding the function itself.

    4. Some directives were written not in order of increasing version number.

    5. In some places parameters were marked up as name. name is commonly used for parameters.

    @serhiy-storchaka serhiy-storchaka added 3.10 only security fixes 3.11 only security fixes labels Feb 17, 2022
    @serhiy-storchaka serhiy-storchaka added docs Documentation in the Doc dir topic-asyncio type-feature A feature request or enhancement 3.10 only security fixes 3.11 only security fixes labels Feb 17, 2022
    @serhiy-storchaka serhiy-storchaka added docs Documentation in the Doc dir topic-asyncio type-feature A feature request or enhancement labels Feb 17, 2022
    @serhiy-storchaka
    Copy link
    Member Author

    1. The loop parameter of Task() was documented as both removed and required (if there is no current event loop) in 3.10.

    @serhiy-storchaka
    Copy link
    Member Author

    New changeset 2923d87 by Serhiy Storchaka in branch 'main':
    bpo-46777: Fix incorrect use of directives in asyncio documentation (GH-31388)
    2923d87

    @miss-islington
    Copy link
    Contributor

    New changeset 6eb3477 by Miss Islington (bot) in branch '3.10':
    bpo-46777: Fix incorrect use of directives in asyncio documentation (GH-31388)
    6eb3477

    @asvetlov
    Copy link
    Contributor

    1. The loop parameter of Task() was documented as both removed and required (if there is no current event loop) in 3.10.

    I think we should drop Task() constructor definition from Task Object docs https://docs.python.org/3/library/asyncio-task.html#task-object but create 'asyncio-extending.rst' (suggest better name please) with low-level task documentation for guys who want to create their own task class.

    Task constructor could be documented here along with _register_task(), _enter_task(), _leave_task(), _unregister_task(). They might be useful for ones who implements a custom task factories.

    @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.10 only security fixes 3.11 only security fixes docs Documentation in the Doc dir topic-asyncio type-feature A feature request or enhancement
    Projects
    None yet
    Milestone
    No milestone
    Development

    No branches or pull requests
    3 participants
    @asvetlov @serhiy-storchaka @miss-islington