DOC: clarify corr behaviour when using a callable (pandas-dev#25732)

fixes pandas-dev#25726

Author: fbnrst

pandas/core/frame.py

@@ -7021,8 +7021,9 @@ def corr(self, method='pearson', min_periods=1):
             * kendall : Kendall Tau correlation coefficient
             * spearman : Spearman rank correlation
             * callable: callable with input two 1d ndarrays
-                and returning a float
-
+                and returning a float. Note that the returned matrix from corr
+                will have 1 along the diagonals and will be symmetric
+                regardless of the callable's behavior
                 .. versionadded:: 0.24.0
 
         min_periods : int, optional

pandas/core/series.py

@@ -2128,8 +2128,10 @@ def corr(self, other, method='pearson', min_periods=None):
             * pearson : standard correlation coefficient
             * kendall : Kendall Tau correlation coefficient
             * spearman : Spearman rank correlation
-            * callable: callable with input two 1d ndarray
-                and returning a float
+            * callable: callable with input two 1d ndarrays
+                and returning a float. Note that the returned matrix from corr
+                will have 1 along the diagonals and will be symmetric
+                regardless of the callable's behavior
                 .. versionadded:: 0.24.0
 
         min_periods : int, optional