-
-
Notifications
You must be signed in to change notification settings - Fork 29.4k
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
bpo-46076: Improve documentation for per-attribute docstrings with __slots__
#30109
Conversation
The pydoc code currently checks specifically for dicts, so perhaps the docs should specify only those are expected (or that code changed)? |
Good catch! Whether the pydoc implementation should be changed is arguable, but I think that discussion should happen in another issue — for now, I'll just update this patch to note that only |
@stevendaprano, you've been heavily involved in the recent python-ideas thread on this topic — any thoughts on this PR? 🙂 |
One thing I'm unsure of: is there anywhere else that this feature should be noted? I couldn't find a "docstring tutorial" where a mention of this feature would easily fit in. (If there are any other places where a mention would be good, I think a link to the data model would suffice — I'm not suggesting duplicating documentation of this feature in multiple places.) |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks! This was always a very useful little feature not so many people know about. 👍
The style of the reference manual is terse. Please just make a compact one-line entry noting that _slots_ can accept a dictionary and that the inspect module treats the values of that dictionary as docstrings for the slots. |
Misc/NEWS.d/next/Documentation/2021-12-14-22-27-49.bpo-46076.nYQ9a8.rst
Outdated
Show resolved
Hide resolved
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
really great improvement!
@rhettinger, I absolutely take your point that this PR, as currently written, is out of keeping with the style of the rest of the data model documentation. However, I do think the example is helpful, and this feature is not currently documented anywhere else. If I pare this PR down to a single sentence, as you suggest, would you be open to a proposal (in a separate PR) to add a mention of this feature in the Descriptor HowTo? I can't think of anywhere else where an example of this sort would fit well; |
Thanks Alex, this looks good to me. And thanks Raymond for doing the
work in the first place all those releases back.
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
Several thoughts:
|
Thanks for the feedback, Raymond -- I appreciate you taking the time! I have made the requested changes; please review again. |
Thanks for making the requested changes! @rhettinger: please review the changes made to this pull request. |
Thanks @AlexWaygood for the PR, and @rhettinger for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10. |
GH-30206 is a backport of this pull request to the 3.10 branch. |
Thanks for the PR. |
GH-30207 is a backport of this pull request to the 3.9 branch. |
…_slots__` (pythonGH-30109) (cherry picked from commit aeb9ef4) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
…_slots__` (pythonGH-30109) (cherry picked from commit aeb9ef4) Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
https://bugs.python.org/issue46076