DOC: Address reviewer comments

Author: gfyoung

pandas/core/generic.py

@@ -2063,57 +2063,73 @@ def __delitem__(self, key):
 
     def take(self, indices, axis=0, convert=True, is_copy=True, **kwargs):
         """
-        Return an object formed from the elements in the given indices along an
-        axis
+        Return the elements in the given *positional* indices along an axis.
+
+        This means that we are not indexing according to actual values in
+        the index attribute of the object. We are indexing according to the
+        actual position of the element in the object's array of values.
 
         Parameters
         ----------
-        indices : list / array of ints
+        indices : array-like
+            An array of ints indicating which positions to take.
         axis : int, default 0
-        convert : translate neg to pos indices (default)
-        is_copy : mark the returned frame as a copy
+            The axis on which to select elements. "0" means that we are
+            selecting rows, "1" means that we are selecting columns, etc.
+        convert : bool, default True
+            Whether to convert negative indices to positive ones.
+        is_copy : bool, default True
+            Whether to return a copy of the original object or not.
 
         Examples
         --------
-        >>> import numpy as np
-        >>> import pandas as pd
         >>> df = pd.DataFrame([('falcon', 'bird',    389.0),
                                ('parrot', 'bird',     24.0),
                                ('lion',   'mammal',   80.5),
                                ('monkey', 'mammal', np.nan)],
-                              columns=('name', 'class', 'max_speed'))
+                              columns=('name', 'class', 'max_speed'),
+                              index=[0, 3, 2, 1])
         >>> df
              name   class  max_speed
         0  falcon    bird      389.0
-        1  parrot    bird       24.0
+        3  parrot    bird       24.0
         2    lion  mammal       80.5
-        3  monkey  mammal        NaN
+        1  monkey  mammal        NaN
 
-        Take elements at indices 0 and 3 along the axis 0 (default)
+        Take elements at positions 0 and 3 along the axis 0 (default).
+
+        Note how the actual indices selected (0 and 1) do not correspond to
+        our selected indices 0 and 3. That's because we are selecting the 0th
+        and 3rd rows, not rows whose indices equal 0 and 3.
 
         >>> df.take([0, 3])
         0  falcon    bird      389.0
-        3  monkey  mammal        NaN
+        1  monkey  mammal        NaN
 
         Take elements at indices 1 and 2 along the axis 1
 
         >>> df.take([1, 2], axis=1)
             class  max_speed
         0    bird      389.0
-        1    bird       24.0
+        3    bird       24.0
         2  mammal       80.5
-        3  mammal        NaN
+        1  mammal        NaN
 
-        Also, we may take elements using negative integers for pos indices
+        We may take elements using negative integers for positive indices.
 
         >>> df.take([-1, -2])
              name   class  max_speed
-        3  monkey  mammal        NaN
+        1  monkey  mammal        NaN
         2    lion  mammal       80.5
 
         Returns
         -------
         taken : type of caller
+            An array-like containing the elements taken from the object.
+
+        See Also
+        --------
+        ndarray.take
         """
         nv.validate_take(tuple(), kwargs)
         self._consolidate_inplace()