Make Series.map() documentation a bit more verbose

Author: manuels <[email protected]>

Closes pandas-dev#15235 from manuels/patch-1 and squashes the following commits:

c5113f2 [manuels] Make Series.map() documentation a bit more verbose

Author: manuels

pandas/core/series.py

@@ -2089,13 +2089,15 @@ def map(self, arg, na_action=None):
         Examples
         --------
 
-        Map inputs to outputs
+        Map inputs to outputs (both of type `Series`)
 
+        >>> x = pd.Series([1,2,3], index=['one', 'two', 'three'])
         >>> x
         one   1
         two   2
         three 3
 
+        >>> y = pd.Series(['foo', 'bar', 'baz'], index=[1,2,3])
         >>> y
         1  foo
         2  bar
@@ -2106,6 +2108,16 @@ def map(self, arg, na_action=None):
         two   bar
         three baz
 
+        Mapping a dictionary keys on the index labels works similar as
+        with a `Series`:
+
+        >>> z = {1: 'A', 2: 'B', 3: 'C'}
+
+        >>> x.map(z)
+        one   A
+        two   B
+        three C
+
         Use na_action to control whether NA values are affected by the mapping
         function.
 
@@ -2127,6 +2139,11 @@ def map(self, arg, na_action=None):
         3                     NaN
         dtype: object
 
+        See Also
+        --------
+        Series.apply: For applying more complex functions on a Series
+        DataFrame.apply: Apply a function row-/column-wise
+        DataFrame.applymap: Apply a function elementwise on a whole DataFrame
         """
 
         if is_extension_type(self.dtype):