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

Document exceptions raised by functions in utils #544

Merged
merged 3 commits into from
Aug 19, 2022

Conversation

MrMino
Copy link
Contributor

@MrMino MrMino commented May 6, 2022

Closes #543.

Added :raises ...: clauses to documentation of functions from packaging.utils.
Class names have been given by their full import path, since they are not mentioned anywhere else in the documentation.

image

image

@brettcannon
Copy link
Member

Class names have been given by their full import path, since they are not mentioned anywhere else in the documentation.

Maybe we should change that? No reason to keep the exceptions undocumented.

@MrMino
Copy link
Contributor Author

MrMino commented May 9, 2022

Done. Here's the outcome:

Class names in raises clauses of parse_... functions are clickable

image

Exception classes descriptions:

image

@MrMino
Copy link
Contributor Author

MrMino commented May 19, 2022

@brettcannon Anything else? Is the style / wording acceptable?

@brettcannon
Copy link
Member

Anything else?

Nope, just me not being sick so I had time to review. 😅

@brettcannon brettcannon enabled auto-merge (squash) May 20, 2022 22:40
@MrMino MrMino requested a review from brettcannon July 11, 2022 13:51
Copy link
Member

@brettcannon brettcannon left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's best to keep the docs for exceptions generic in case other code uses the exceptions in the future.

docs/utils.rst Outdated Show resolved Hide resolved
docs/utils.rst Outdated Show resolved Hide resolved
@brettcannon
Copy link
Member

Apologies for taking so long to get to this! Luckily 3.11.0.rc1 is getting cut today and I caught up to my review queue so I'm apparently only backed up until PRs created in May 😅.

auto-merge was automatically disabled August 16, 2022 03:18

Head branch was pushed to by a user without write access

@MrMino
Copy link
Contributor Author

MrMino commented Aug 16, 2022

Fixed. Thanks :).

Edit: also linearized the log, fixed a missing word.

Also applied suggestions from code review

Co-authored-by: Brett Cannon <[email protected]>
@brettcannon brettcannon self-requested a review August 16, 2022 20:51
@brettcannon brettcannon reopened this Aug 19, 2022
@brettcannon brettcannon merged commit cb2b89f into pypa:main Aug 19, 2022
@brettcannon
Copy link
Member

Thanks!

KOLANICH pushed a commit to KOLANICH-libs/packaging that referenced this pull request Nov 30, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Document exceptions raised by functions in packaging.utils
2 participants