Deduplicate inherited docstrings. #12255
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
timhoffm
reviewed
Sep 24, 2018
lib/matplotlib/text.py
Outdated
| ---------- | ||
| clipbox : `matplotlib.transforms.Bbox` | ||
| """ | ||
| def set_clip_box(self, clipbox): # inherited docstring. |
There was a problem hiding this comment.
It's good to have a comment for the inherited docstring. This documents the intention not to have a docstring there and prevents future accidential additions. Can we move the comment
to the place where the docstring should usually be:
def set_clip_box(self, clipbox):
# docstring inherited
That way it's easy to see and we don't run into linewidth limitations with longer signatures.
Also, for some reason, I'd prefer # docstring inherited over # inherited docstring if you don't mind. (Can't really explain, but it feels more appropriate.)
|
Btw. thanks for bringing this up. Handling inherited docstrings was on my todo list 😄 |
f46e78c to
16414ac
Compare
timhoffm
approved these changes
Sep 25, 2018
62b7059 to
7b5924b
Compare
Since Py3.5, inspect.getdoc inherits method docstrings from super-methods (pydoc, sphinx, and IPython's ? do the same). Take advantage of this to deduplicate some docstrings that were already defined for the Artist base methods. Note that Text.set_clip_path's docstring had actually not been updated when we updated the docstring of Artist.set_clip_path... We could add a decorator to check that the docstring is *actually* getting inherited but that seems totally overkill.
7b5924b to
c83d6ac
Compare
dopplershift
approved these changes
Sep 25, 2018
6 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Since Py3.5, inspect.getdoc inherits method docstrings from
super-methods (pydoc, sphinx, and IPython's ? do the same).
Take advantage of this to deduplicate some docstrings that were already
defined for the Artist base methods. Note that Text.set_clip_path's
docstring had actually not been updated when we updated the docstring of
Artist.set_clip_path...
We could add a decorator to check that the docstring is actually
getting inherited but that seems totally overkill.
PR Summary
PR Checklist