DOC: Improve docs (GH19312) for Series.nonzero()

Author: drorata

pandas/core/series.py

@@ -490,13 +490,14 @@ def compress(self, condition, *args, **kwargs):
 
     def nonzero(self):
         """
-        Return the indices of the elements that are non-zero
+        Return the integer indices of the elements that are non-zero
 
         This method is equivalent to calling `numpy.nonzero` on the
         series data. For compatibility with NumPy, the return value is
         the same (a tuple with an array of indices for each dimension),
         but it will always be a one-item tuple because series only have
-        one dimension.
+        one dimension. Note that the method returns the *integer* indices
+        regardless of the index of the series.
 
         Examples
         --------
@@ -508,6 +509,15 @@ def nonzero(self):
         3    4
         dtype: int64
 
+        >>> s = pd.Series([0, 3, 0, 4])
+        >>> s.index=['a', 'b', 'c', 'd']
+        >>> s.nonzero() # same return although index of s is different
+        (array([1, 3]),)
+        >>> s.iloc[s.nonzero()[0]]
+        b    3
+        d    4
+        dtype: int64
+
         See Also
         --------
         numpy.nonzero