DOC: Documentation for pandas.core.indexes.api

pandas/core/indexes/api.py

@@ -44,16 +44,20 @@
 
 
 def _get_objs_combined_axis(objs, intersect=False, axis=0, sort=True):
-    # Extract combined index: return intersection or union (depending on the
-    # value of "intersect") of indexes on given axis, or None if all objects
-    # lack indexes (e.g. they are numpy arrays)
+    """Extract combined index: return intersection or union (depending on the
+    value of "intersect") of indexes on given axis, or None if all objects
+    lack indexes (e.g. they are numpy arrays)
+    """
     obs_idxes = [obj._get_axis(axis) for obj in objs
                  if hasattr(obj, '_get_axis')]
     if obs_idxes:
         return _get_combined_index(obs_idxes, intersect=intersect, sort=sort)
 
 
 def _get_combined_index(indexes, intersect=False, sort=False):
+    """Return the union or intersection of indexes
+    """
+
     # TODO: handle index names!
     indexes = com.get_distinct_objs(indexes)
     if len(indexes) == 0:
@@ -77,6 +81,10 @@ def _get_combined_index(indexes, intersect=False, sort=False):
 
 
 def _union_indexes(indexes, sort=True):
+    """Return the union of indexes
+
+    The behavior of sort and names is not consistent.
+    """
     if len(indexes) == 0:
         raise AssertionError('Must have at least 1 Index to union')
     if len(indexes) == 1:
@@ -88,6 +96,10 @@ def _union_indexes(indexes, sort=True):
     indexes, kind = _sanitize_and_check(indexes)
 
     def _unique_indices(inds):
+        """Convert indexes to lists and concatenate them, removing duplicates
+
+        The final dtype is inferred.
+        """
         def conv(i):
             if isinstance(i, Index):
                 i = i.tolist()
@@ -126,6 +138,16 @@ def conv(i):
 
 
 def _sanitize_and_check(indexes):
+    """Verify the type of indexes and convert lists to Index
+
+    Cases:
+
+    - [list, list, ...]: Return ([list, list, ...], 'list')
+    - [list, Index, ...]: Return _sanitize_and_check([Index, Index, ...])
+        Lists are sorted and converted to Index
+    - [Index, Index, ...]: Return ([Index, Index, ...], TYPE)
+        TYPE = 'special' if at least one special type, 'array' otherwise
+    """
     kinds = list({type(index) for index in indexes})
 
     if list in kinds:
@@ -144,6 +166,11 @@ def _sanitize_and_check(indexes):
 
 
 def _get_consensus_names(indexes):
+    """Give a consensus 'names' to indexes
+
+    If there's exactly one non-empty 'names', return this,
+    otherwise, return empty.
+    """
 
     # find the non-none names, need to tupleify to make
     # the set hashable, then reverse on return
@@ -155,6 +182,8 @@ def _get_consensus_names(indexes):
 
 
 def _all_indexes_same(indexes):
+    """Determine if all indexes contain the same elements
+    """
     first = indexes[0]
     for index in indexes[1:]:
         if not first.equals(index):