Addresses issue #5704. Makes usage of parameters clearer

[dsquareindia]

Just added a few lines to make the dependence of the different parameters clearer.

[dsquareindia]

@tacaswell please have a look.

[tacaswell]

It looks like there are some pep8 issues:

======================================================================
FAIL: matplotlib.tests.test_coding_standards.test_pep8_conformance_installed_files
----------------------------------------------------------------------
Traceback (most recent call last):
  File "/home/travis/build/matplotlib/matplotlib/venv/lib/python3.5/site-packages/nose/case.py", line 198, in runTest
    self.test(*self.arg)
  File "/home/travis/build/matplotlib/matplotlib/lib/matplotlib/tests/test_coding_standards.py", line 249, in test_pep8_conformance_installed_files
    expected_bad_files=expected_bad_files)
  File "/home/travis/build/matplotlib/matplotlib/lib/matplotlib/tests/test_coding_standards.py", line 143, in assert_pep8_conformance
    assert_equal(result.total_errors, 0, msg)
AssertionError: 3 != 0 : Found code syntax errors (and warnings):
/home/travis/build/matplotlib/matplotlib/lib/matplotlib/axes/_axes.py:636:80: E501 line too long (85 > 79 characters)
/home/travis/build/matplotlib/matplotlib/lib/matplotlib/axes/_axes.py:639:80: E501 line too long (81 > 79 characters)
/home/travis/build/matplotlib/matplotlib/lib/matplotlib/axes/_axes.py:651:80: E501 line too long (82 > 79 characters)
----------------------------------------------------------------------

Can you please wrap those lines to <80 characters?

[tacaswell]

This does not default to 'data'.

I would add something to the body of this parameter like 'see xycoords to control what coordinate system this value is interpreted in' and something similar for xytext.

[dsquareindia]

Oh sorry I'll remove the default value for xy. Yes what you said makes it much clearer but then I think I'll have to use the next line. Is it fine if I do so? Ideally I don't really want to do that though...

[tacaswell]

Use as many lines as you need.

Not everything can be documented in about half a tweet

On Tue, Dec 22, 2015, 01:34 Devashish Deshpande notifications@github.com
wrote:

In lib/matplotlib/axes/_axes.py
#5709 (comment):

@@ -632,22 +632,21 @@ def annotate(self, _args, *_kwargs):
s : string
label

•    xy : (x, y)
  

•        position of element to annotate
  

•    xy : (x, y) , default: "data"
  

Oh sorry I'll remove the default value for xy. Yes what you said makes it
much clearer but then I think I'll have to use the next line. Is it fine if
I do so? Ideally I don't really want to do that though...

—
Reply to this email directly or view it on GitHub
https://github.com/matplotlib/matplotlib/pull/5709/files#r48225539.

[dsquareindia]

@tacaswell I'm not able to understand why it's failing now....

[tacaswell]

Restarted, That particular failure is checking relative speeds, but the tests run on VMs without any performance guarantees so it intermittently fails (see that one maybe once or twice a week).

[dsquareindia]

Oh alright thanks!

[tacaswell]

Thanks!

Contributions to documentation are as or more important as code contributions. 👍

[tacaswell]

backported to 1.5.x as 82b29ae

[dsquareindia]

Will surely keep that in mind :-)