DOC: Fixed documentation for pivot_table margins (pandas-dev#48916) (p…

…andas-dev#48965)

* DOC: Fixed documentation for pivot_table margins (pandas-dev#48916)

The documentation for the margins parameter of pivot_table
was incorrect. It said that the parameter added rows and columns,
but it actually passed them to aggfunc. I used the documentation
from the user guide to replace the old documentation, as well as
added a sentence to the documentation for aggfunc that explained
its role in calculating margins.

* Update pandas/core/frame.py

Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com>

Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com>

pandas/core/frame.py

@@ -8604,12 +8604,15 @@ def pivot(
             hierarchical columns whose top level are the function names
             (inferred from the function objects themselves)
             If dict is passed, the key is column to aggregate and value
-            is function or list of functions.
+            is function or list of functions. If ``margin=True``,
+            aggfunc will be used to calculate the partial aggregates.
         fill_value : scalar, default None
             Value to replace missing values with (in the resulting pivot table,
             after aggregation).
         margins : bool, default False
-            Add all row / columns (e.g. for subtotal / grand totals).
+            If ``margins=True``, special ``All`` columns and rows
+            will be added with partial group aggregates across the categories
+            on the rows and columns.
         dropna : bool, default True
             Do not include columns whose entries are all NaN. If True,
             rows with a NaN value in any column will be omitted before