DOC: Add examples and notes to empty documentation

pandas/core/generic.py

@@ -842,7 +842,39 @@ def __contains__(self, key):
 
     @property
     def empty(self):
-        """True if NDFrame is entirely empty [no items]"""
+        """True if NDFrame is entirely empty [no items], i.e. any of the axes
+        are of length 0.
+
+        Notes
+        -----
+        If NDFrame contains only NaNs, it is still not considered empty. See
+        the example below.
+
+        Examples
+        --------
+        An example of an actual empty DataFrame. Notice the index is empty:
+
+        >>> df_empty = pd.DataFrame({'A' : []})
+        >>> df_empty
+        Empty DataFrame
+        Columns: [A]
+        Index: []
+        >>> df_empty.empty
+        True
+
+        If we only have NaNs in our DataFrame, it is not considered empty! We
+        will need to drop the NaNs to make the DataFrame empty:
+
+        >>> df = pd.DataFrame({'A' : [np.nan]})
+        >>> df
+            A
+        0 NaN
+        >>> df.empty
+        False
+        >>> df.dropna().empty
+        True
+
+        """
         return not all(len(self._get_axis(a)) > 0 for a in self._AXIS_ORDERS)
 
     def __nonzero__(self):