Improve Artist docstrings #11951
Improve Artist docstrings #11951
Conversation
lib/matplotlib/artist.py
Outdated
| :meth:`remove_callback` later. | ||
| Parameters | ||
| ---------- | ||
| func : Callable[Artist] |
There was a problem hiding this comment.
Technically that's Callable[[Artist], Any] (I think).
There was a problem hiding this comment.
Reverted to just callback. In such cases, I will write the required signature as a type-annotated example in such cases.
IMO def func(artist: Artist) -> Any is easier to understand than Callable[[Artist], Any].
lib/matplotlib/artist.py
Outdated
|
|
||
| :meth:`add_callback` | ||
| For adding callbacks | ||
| Remove a callback based on its observer *id*. |
There was a problem hiding this comment.
Changed to "observer id" without markup. "observer oid" would be sort of double.
lib/matplotlib/artist.py
Outdated
| @@ -220,8 +223,8 @@ def axes(self, new_axes): | |||
| @property | |||
| def stale(self): | |||
| """ | |||
| If the artist is 'stale' and needs to be re-drawn for the output to | |||
| match the internal state of the artist. | |||
| A boolean flag indicating if the artist is 'stale' and needs to be | |||
There was a problem hiding this comment.
Actually I prefer the old version (after s/If/Whether).
lib/matplotlib/artist.py
Outdated
| Return a list of the child :class:`Artist`s this | ||
| :class:`Artist` contains. | ||
| """ | ||
| """Return a list of the child `.Artist`\ s this `.Artist` contains.""" |
There was a problem hiding this comment.
I think this should be a raw string with no space after the backslash.
lib/matplotlib/artist.py
Outdated
|
|
||
| Parameters | ||
| ---------- | ||
| picker : callable | ||
| picker : Callable[Artist, MouseEvent] |
There was a problem hiding this comment.
See above. I would also not bother repeating the signature just below. (Or we can just decide to write type annotations in "signature" form as below; either way I don't think repeating the same info twice in slightly different formats really helps here.)
There was a problem hiding this comment.
Switching to just "callable" and giving an example signature below (see also comment above).
lib/matplotlib/artist.py
Outdated
|
|
||
| A 3-tuple with the following elements: | ||
|
|
||
| * `scale`: The amplitude of the wiggle perpendicular to the | ||
| - *scale*: The amplitude of the wiggle perpendicular to the |
There was a problem hiding this comment.
Unindent the list. Probably also remove the blank lines in between.
lib/matplotlib/artist.py
Outdated
| contained in self. | ||
|
|
||
| *match* can be | ||
| Recursively find all `.Artist` instances contained in self. |
There was a problem hiding this comment.
in *self* perhaps, or in the artist (as above)
lib/matplotlib/artist.py
Outdated
| The result will only contain artists for which the function | ||
| returns *True*. | ||
| - A class instance: e.g., `.Line2D`. The result will only contain | ||
| artists of this class or it's subclasses (``isinstance`` check). |
lib/matplotlib/artist.py
Outdated
| registered callbacks. | ||
| Call all of the registered callbacks. | ||
|
|
||
| This function is triggered internally when a property changed. |
There was a problem hiding this comment.
"property changed" > "property is changed"
|
Thanks @timhoffm ! |
PR Summary
artist_api.rst. There's nothing added or removed in this file.Motivation: Since the top-level grouping is semantically, I try to order related functions within the sections in a logical way. In particular I move getters and setters next to each other.
There's still a bit more to do within this module, but I think the PR is big enough for now.