DOC: Improve the docstring of DataFrame.equals()

pandas/core/generic.py

@@ -1303,8 +1303,59 @@ def __invert__(self):
 
     def equals(self, other):
         """
-        Determines if two NDFrame objects contain the same elements. NaNs in
-        the same location are considered equal.
+        Test whether two DataFrame objects contain the same elements.
+
+        This function allows two DataFrame objects to be compared against
+        each other to see if they same shape and elements. NaNs in the same
+        location are considered equal. The column headers do not need to have
+        the same type, but the elements within the columns must be
+        the same dtype.
+
+        Parameters
+        ----------
+        other : DataFrame
+            The other DataFrame to be compared with the first.
+
+        Returns
+        -------
+        bool
+            True if all elements are the same in both DataFrames, False
+            otherwise.
+
+        See Also
+        --------
+        pandas.Series.eq : Compare two Series objects of the same length
+            and return a Series where each element is True if the element
+            in each Series is equal, False otherwise.
+
+        numpy.array_equal : Return True if two arrays have the same shape
+            and elements, False otherwise.
+
+        Notes
+        -----
+        This function requires that the elements have the same dtype as their
+        respective elements in the other DataFrame. However, the indices do
+        not need to have the same type, as long as they are still considered
+        equal.
+
+        Examples
+        --------
+        >>> a = pd.DataFrame({1:[0], 0:[1]})
+        >>> b = pd.DataFrame({1.0:[0], 0.0:[1]})
+
+        DataFrames a and b have the same element types and values, but have
+        different types for the indices, which will still return True.
+
+        >>> a.equals(b)
+        True
+
+        DataFrames a and c have different types for the same values for their
+        elements, and will return False even though the indices are the same
+        values and types.
+
+        >>> c = pd.DataFrame({1:[0.0], 0:[1.0]})
+        >>> a.equals(c)
+        False
         """
         if not isinstance(other, self._constructor):
             return False