Merge pull request matplotlib#2208 from NelleV/MEP10_annotate

DOC annotate is now in numpydoc format

Author: efiring

lib/matplotlib/axes/_axes.py

@@ -537,15 +537,47 @@ def annotate(self, *args, **kwargs):
         Create an annotation: a piece of text referring to a data
         point.
 
-        Call signature::
+        Parameters
+        ----------
+        s : string
+            label
 
-          annotate(s, xy, xytext=None, xycoords='data',
-                   textcoords='data', arrowprops=None, **kwargs)
+        xy : (x, y)
+            position of element to annotate
 
-        Keyword arguments:
+        xytext : (x, y) , optional, default: None
+            position of the label `s`
+
+        xycoords : string, optional, default: "data"
+            string that indicates what tye of coordinates `xy` is. Examples:
+            "figure points", "figure pixels", "figure fraction", "axes
+            points", .... See `matplotlib.text.Annotation` for more details.
+
+        textcoords : string, optional, default: None
+            string that indicates what type of coordinates `text` is. Examples:
+            "figure points", "figure pixels", "figure fraction", "axes
+            points", .... See `matplotlib.text.Annotation` for more details.
+
+        arrowprops : `matplotlib.lines.Line2D` properties, optional, default: None
+            Dictionnary of line properties for the arrow that connects the
+            annotation to the point. If the dictionnary has a key
+            `arrowstyle`, a `FancyArrowPatch` instance is created and drawn.
+            See `matplotlib.text.Annotation` for more details on valid
+            options.
+
+        Returns
+        -------
+        a : `~matplotlib.text.Annotation`
+
+
+        Other parameters
+        -----------------
 
         %(Annotation)s
 
+        Examples
+        --------
+
         .. plot:: mpl_examples/pylab_examples/annotation_demo2.py
         """
         a = mtext.Annotation(*args, **kwargs)
@@ -710,7 +742,7 @@ def axhspan(self, ymin, ymax, xmin=0, xmax=1, **kwargs):
         Return value is a :class:`matplotlib.patches.Polygon`
         instance.
 
-        Examples:
+       Examples:
 
         * draw a gray rectangle from *y* = 0.25-0.75 that spans the
           horizontal extent of the axes::