DOC: Correct and expand Series.nonzero docstring

- Mention that a tuple of indices is returned and explain why.
- Instead of numpy.ndarray.nonzero, point to numpy.nonzero, which has
  the full documentation.
- Add example.

Author: kyleam

pandas/core/series.py

@@ -331,11 +331,27 @@ def compress(self, condition, axis=0, out=None, **kwargs):
 
     def nonzero(self):
         """
-        return the a boolean array of the underlying data is nonzero
+        Return the indices of the elements that are non-zero
 
-        See also
+        This method is equivalent to calling `numpy.nonzero` on the
+        series data. For compatability 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.
+
+        Examples
+        --------
+        >>> s = pd.Series([0, 3, 0, 4])
+        >>> s.nonzero()
+        (array([1, 3]),)
+        >>> s.iloc[s.nonzero()[0]]
+        1    3
+        3    4
+        dtype: int64
+
+        See Also
         --------
-        numpy.ndarray.nonzero
+        numpy.nonzero
         """
         return self.values.nonzero()