docstring overhaul: fix bullet list and merge duplicated infos betwee…

…n class and init docstrings
matplotlib · tacaswell · Aug 26, 2017 · Jun 6, 2016 · Jun 6, 2016 · Jun 7, 2016
commit 3ec1dbd3f2ba8e255243807eebe651ad982f10eb
diff --git a/examples/api/engineering_formatter.py b/examples/api/engineering_formatter.py
@@ -17,7 +17,7 @@
 # Create artificial data to plot.
 # The x data span over several decades to demonstrate several SI prefixes.
 xs = np.logspace(1, 9, 100)
-ys = (0.8 + 0.4*prng.uniform(size=100))*np.log10(xs)**2
+ys = (0.8 + 0.4 * prng.uniform(size=100)) * np.log10(xs)**2
 
 # Figure width is doubled (2*6.4) to display nicely 2 subplots side by side.
 fig, (ax0, ax1) = plt.subplots(ncols=2, figsize=(12.8, 4.8))

diff --git a/lib/matplotlib/tests/test_ticker.py b/lib/matplotlib/tests/test_ticker.py
@@ -576,18 +576,19 @@ def test_params(self, input, expected):
         """
         Test the formatting of EngFormatter for various values of the 'places'
         argument, in several cases:
-            0.  without a unit symbol but with a (default) space separator;
-            1.  with both a unit symbol and a (default) space separator;
-            2x. with both a unit symbol and some non default separators;
-            3x. without a unit symbol but with some non default separators.
+            0. without a unit symbol but with a (default) space separator;
+            1. with both a unit symbol and a (default) space separator;
+            2. with both a unit symbol and some non default separators;
+            3. without a unit symbol but with some non default separators.
+        Note that cases 2. and 3. are looped over several separator strings.
         """
 
         UNIT = 's'  # seconds
         DIGITS = '0123456789'  # %timeit showed 10-20% faster search than set
 
         # Case 0: unit='' (default) and sep=' ' (default).
         # 'expected' already corresponds to this reference case.
-        exp_outputs = (_s for _s in expected)  # simple copy of 'expected'
+        exp_outputs = expected
         formatters = (
             mticker.EngFormatter(),  # places=None (default)
             mticker.EngFormatter(places=0),
@@ -612,8 +613,9 @@ def test_params(self, input, expected):
         # Test several non default separators: no separator, a narrow
         # no-break space (unicode character) and an extravagant string.
         for _sep in ("", "\u202f", "@_@"):
-            # Case 2x: unit=UNIT and sep=_sep.
-            # Remove the space separator from the reference case.
+            # Case 2: unit=UNIT and sep=_sep.
+            # Replace the default space separator from the reference case
+            # with the tested one `_sep` and append a unit symbol to it.
             exp_outputs = (_s + _sep + UNIT if _s[-1] in DIGITS  # no prefix
                            else _s.replace(" ", _sep) + UNIT
                            for _s in expected)
@@ -625,9 +627,9 @@ def test_params(self, input, expected):
             for _formatter, _exp_output in zip(formatters, exp_outputs):
                 assert _formatter(input) == _exp_output
 
-            # Case 3x: unit='' (default) and sep=_sep.
-            # Remove the space separator from the reference case and append
-            # a unit symbol to it.
+            # Case 3: unit='' (default) and sep=_sep.
+            # Replace the default space separator from the reference case
+            # with the tested one `_sep`. Reference case is already unitless.
             exp_outputs = (_s.replace(" ", _sep) for _s in expected)
             formatters = (
                 mticker.EngFormatter(sep=_sep),  # places=None (default)

diff --git a/lib/matplotlib/ticker.py b/lib/matplotlib/ticker.py
@@ -1184,19 +1184,8 @@ class EngFormatter(Formatter):
     """
     Formats axis values using engineering prefixes to represent powers
     of 1000, plus a specified unit, e.g., 10 MHz instead of 1e7.
-
-    `unit` is a string containing the abbreviated name of the unit,
-    suitable for use with single-letter representations of powers of
-    1000. For example, 'Hz' or 'm'.
-
-    `places` is the precision with which to display the number,
-    specified in digits after the decimal point (there will be between
-    one and three digits before the decimal point).
-
-    `sep` is the separator (a string) that is used between the number
-    and the prefix/unit. For example, '3.14 mV' if `sep` is " " (default)
-    and '3.14mV' if `sep` is "".
     """
+
     # The SI engineering prefixes
     ENG_PREFIXES = {
         -24: "y",
@@ -1222,20 +1211,26 @@ def __init__(self, unit="", places=None, sep=" "):
         """
         Parameters
         ----------
-        unit: string (default: "")
-            Unit symbol to use.
-
-        places: int (default: None)
-            Precision, i.e. number of digits after the decimal point.
-            If it is None, falls back to the floating point format '%g'.
-
-        sep: string (default: " ")
-            String used between the value and the prefix/unit. Beside the
-            default behavior, some other useful use cases may be:
-            * sep="" to append directly the prefix/unit to the value;
-            * sep="\\u2009" to use a thin space;
-            * sep="\\u202f" to use a narrow no-break space;
-            * sep="\\u00a0" to use a no-break space.
+        unit : str (default: "")
+            Unit symbol to use, suitable for use with single-letter
+            representations of powers of 1000. For example, 'Hz' or 'm'.
+
+        places : int (default: None)
+            Precision with which to display the number, specified in
+            digits after the decimal point (there will be between one
+            and three digits before the decimal point). If it is None,
+            falls back to the floating point format '%g'.
+
+        sep : str (default: " ")
+            Separator used between the value and the prefix/unit. For
+            example, one get '3.14 mV' if ``sep`` is " " (default) and
+            '3.14mV' if ``sep`` is "". Besides the default behavior, some
+            other useful options may be:
+
+            * ``sep=""`` to append directly the prefix/unit to the value;
+            * ``sep="\\u2009"`` to use a thin space;
+            * ``sep="\\u202f"`` to use a narrow no-break space;
+            * ``sep="\\u00a0"`` to use a no-break space.
         """
         self.unit = unit
         self.places = places
@@ -1244,7 +1239,8 @@ def __init__(self, unit="", places=None, sep=" "):
     def __call__(self, x, pos=None):
         s = "%s%s" % (self.format_eng(x), self.unit)
         # Remove the trailing separator when there is neither prefix nor unit
-        s = s.strip(self.sep)
+        if len(self.sep) > 0 and s.endswith(self.sep):
+            s = s[:-len(self.sep)]
         return self.fix_minus(s)
 
     def format_eng(self, num):