Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Improve docsting of AxesImage #15562

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.

Sign up for GitHub

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
Merged
merged 1 commit into from
Oct 29, 2019
Merged

Improve docsting of AxesImage #15562

merged 1 commit into from
Oct 29, 2019

Conversation

timhoffm
Copy link
Member

PR Summary

Follow up to #15523.

  • add description for ax parameter
  • add default values
  • some ReST formatting fixes

@timhoffm timhoffm added this to the v3.2.0 milestone Oct 28, 2019
dstansby
dstansby reviewed Oct 29, 2019
View reviewed changes
lib/matplotlib/image.py
Place the [0, 0] index of the array in the upper left or lower left
corner of the axes. The convention 'upper' is typically used for
matrices and images.
extent : tuple
extent : tuple, optional
Copy link
Member

Choose a reason for hiding this comment

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

I thought the policy was to omit 'optional' now since one can check the function signature to see if it's optional?

@timhoffm
Copy link
Member Author

Personally, I wouldn't have a problem with omitting "optional" here.
But after discussion, the minimal consensus was to just allow default: instead of optional, default:. The idea was to have the docstring be fully self-explanatory without the need to to look up the signature.

#14862 (comment)
#14862 (comment)

The current policy is (https://matplotlib.org/devdocs/devel/documenting_mpl.html#parameter-type-descriptions):

As opposed to the numpydoc guide, parameters need not be marked as optional if they have a simple default. This removes unnecessary clutter. The optional aspect is already clear from the presence of a default value. More specifically

  • use {name} : {type}, default: {val} when possible.
  • use {name} : {type}, optional and describe the default in the text if in cannot be explained sufficiently in the above way.

@dstansby
Copy link
Member

Ah fab, thanks for the description (and sorry for not going and looking it up myself), just wanted to double check!

@dstansby dstansby merged commit f7fa86a into matplotlib:master Oct 29, 2019
meeseeksmachine pushed a commit to meeseeksmachine/matplotlib that referenced this pull request Oct 29, 2019
@dstansby
Backport PR matplotlib#15562: Improve docsting of AxesImage
c1c73bd
@meeseeksmachine meeseeksmachine mentioned this pull request Oct 29, 2019
Merged
@timhoffm timhoffm deleted the doc-axesimage branch October 29, 2019 17:25
timhoffm added a commit that referenced this pull request Oct 29, 2019
@timhoffm
Merge pull request #15567 from meeseeksmachine/auto-backport-of-pr-15…
630a2e8 
…562-on-v3.2.x

Backport PR #15562 on branch v3.2.x (Improve docsting of AxesImage)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@dstansby dstansby dstansby approved these changes

Assignees
No one assigned
Labels
Documentation
Projects
None yet
Milestone
v3.2.0
Development

Successfully merging this pull request may close these issues.
2 participants
@timhoffm @dstansby