Merge pull request #7417 from clham/7413

DOC: update df.as_matrix and df.values.  Closes gh7413

Author: jorisvandenbossche

pandas/core/generic.py

@@ -1929,25 +1929,39 @@ def _get_bool_data(self):
 
     def as_matrix(self, columns=None):
         """
-        Convert the frame to its Numpy-array matrix representation. Columns
-        are presented in sorted order unless a specific list of columns is
-        provided.
-
-        NOTE: the dtype will be a lower-common-denominator dtype (implicit
-              upcasting) that is to say if the dtypes (even of numeric types)
-              are mixed, the one that accommodates all will be chosen use this
-              with care if you are not dealing with the blocks
-
-              e.g. if the dtypes are float16,float32         -> float32
-                                     float16,float32,float64 -> float64
-                                     int32,uint8             -> int32
-
+        Convert the frame to its Numpy-array representation. 
+                
+        Parameters
+        ----------
+        columns: list, optional, default:None 
+            If None, return all columns, otherwise, returns specified columns.
 
         Returns
         -------
         values : ndarray
             If the caller is heterogeneous and contains booleans or objects,
-            the result will be of dtype=object
+            the result will be of dtype=object. See Notes.
+
+            
+        Notes
+        ----- 
+        Return is NOT a Numpy-matrix, rather, a Numpy-array.
+        
+        The dtype will be a lower-common-denominator dtype (implicit
+        upcasting); that is to say if the dtypes (even of numeric types)
+        are mixed, the one that accommodates all will be chosen. Use this
+        with care if you are not dealing with the blocks.
+
+        e.g. If the dtypes are float16 and float32, dtype will be upcast to 
+        float32.  If dtypes are int32 and uint8, dtype will be upcase to 
+        int32.
+
+        This method is provided for backwards compatibility. Generally,
+        it is recommended to use '.values'.
+                            
+        See Also
+        --------
+        pandas.DataFrame.values
         """
         self._consolidate_inplace()
         if self._AXIS_REVERSED:
@@ -1956,7 +1970,19 @@ def as_matrix(self, columns=None):
 
     @property
     def values(self):
-        "Numpy representation of NDFrame"
+        """Numpy representation of NDFrame
+        
+        Notes
+        -----
+        The dtype will be a lower-common-denominator dtype (implicit
+        upcasting); that is to say if the dtypes (even of numeric types)
+        are mixed, the one that accommodates all will be chosen. Use this
+        with care if you are not dealing with the blocks.
+
+        e.g. If the dtypes are float16 and float32, dtype will be upcast to 
+        float32.  If dtypes are int32 and uint8, dtype will be upcase to 
+        int32.
+        """
         return self.as_matrix()
 
     @property