DOC: Update the Series.str.len docstring (pandas-dev#22187)

pandas/core/strings.py

@@ -2814,11 +2814,48 @@ def rindex(self, sub, start=0, end=None):
         return self._wrap_result(result)
 
     _shared_docs['len'] = ("""
-    Compute length of each string in the Series/Index.
+    Computes the length of each element in the Series/Index. The element may be
+    a sequence (such as a string, tuple or list) or a collection
+    (such as a dictionary).
 
     Returns
     -------
-    lengths : Series/Index of integer values
+    Series or Index of int
+        A Series or Index of integer values indicating the length of each
+        element in the Series or Index.
+
+    See Also
+    --------
+    str.len : Python built-in function returning the length of an object.
+    Series.size : Returns the length of the Series.
+
+    Examples
+    --------
+    Returns the length (number of characters) in a string. Returns the
+    number of entries for dictionaries, lists or tuples.
+
+    >>> s = pd.Series(['dog',
+    ...                 '',
+    ...                 5,
+    ...                 {'foo' : 'bar'},
+    ...                 [2, 3, 5, 7],
+    ...                 ('one', 'two', 'three')])
+    >>> s
+    0                  dog
+    1
+    2                    5
+    3       {'foo': 'bar'}
+    4         [2, 3, 5, 7]
+    5    (one, two, three)
+    dtype: object
+    >>> s.str.len()
+    0    3.0
+    1    0.0
+    2    NaN
+    3    1.0
+    4    4.0
+    5    3.0
+    dtype: float64
     """)
     len = _noarg_wrapper(len, docstring=_shared_docs['len'], dtype=int)