DOC: update the GroupBy.apply docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant
- [X] closes #19337

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
################ Docstring (pandas.core.groupby.GroupBy.apply)  ################
################################################################################

Apply function ``func``  group-wise and combine the results together.

The function passed to ``apply`` must take a dataframe as its first
argument and return a dataframe, a series or a scalar. ``apply`` will
then take care of combining the results back together into a single
dataframe or series. ``apply`` is therefore a highly flexible
grouping method.

While ``apply`` is a very flexible method, its downside is that
using it can be quite a bit slower than using more specific methods.
Pandas offers a wide range of method that will be much faster
than using ``apply`` for their specific purposes, so try to use them
before reaching for ``apply``.

Parameters
----------
func : function
    A callable that takes a dataframe as its first argument, and
    returns a dataframe, a series or a scalar. In addition the
    callable may take positional and keyword arguments.
args : tuple
    Optional positional and keyword arguments to pass to ``func``.
kwargs : dict
    Optional positional and keyword arguments to pass to ``func``.

Returns
-------
applied : Series or DataFrame

Notes
-----
In the current implementation ``apply`` calls func twice on the
first group to decide whether it can take a fast or slow code
path. This can lead to unexpected behavior if func has
side-effects, as they will take effect twice for the first
group.

Examples
--------

>>> df = pd.DataFrame({'A': 'a a b'.split(), 'B': [1,2,3], 'C': [4,6, 5]})
>>> g = df.groupby('A')

From ``df`` above we can see that ``g`` has two groups, ``a``, ``b``.
Calling ``apply`` in various ways, we can get different grouping results:

Example 1: below the function passed to ``apply`` takes a dataframe as
its argument and returns a dataframe. ``apply`` combines the result for
each group together into a new dataframe:

>>> g[['B','C']].apply(lambda x: x / x.sum())
          B    C
0  0.333333  0.4
1  0.666667  0.6
2  1.000000  1.0

Example 2: The function passed to ``apply`` takes a dataframe as
its argument and returns a series.  ``apply`` combines the result for
each group together into a new dataframe:

>>> g[['B','C']].apply(lambda x: x.max() - x.min())
   B  C
A
a  1  2
b  0  0

Example 3: The function passed to ``apply`` takes a dataframe as
its argument and returns a scalar. ``apply`` combines the result for
each group together into a series, including setting the index as
appropriate:

>>> g.apply(lambda x: x.C.max() - x.B.min())
A
a    5
b    2
dtype: int64

See also
--------
pipe : Apply function to the full GroupBy object instead of to each
    group.
aggregate : Apply aggregate function to the GroupBy object.
transform : Apply function column-by-column to the GroupBy object.

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.core.groupby.GroupBy.apply" correct. :)
```

Labels:
name: Docs
name: Groupby

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20098?src=pr&el=h1) Report
> Merging [#20098](https://codecov.io/gh/pandas-dev/pandas/pull/20098?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/322dbf4f812f47d4eaee5d8afa10e17acf6dbc67?src=pr&el=desc) will **decrease** coverage by `0.26%`.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20098/graphs/tree.svg?token=eZ4WkYLtcO&src=pr&height=150&width=650)](https://codecov.io/gh/pandas-dev/pandas/pull/20098?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20098      +/-   ##
==========================================
- Coverage   91.99%   91.73%   -0.27%     
==========================================
  Files         167      150      -17     
  Lines       50578    49168    -1410     
==========================================
- Hits        46530    45102    -1428     
- Misses       4048     4066      +18
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <ø> (-0.29%)` | :arrow_down: |
| #single | `41.86% <ø> (-0.31%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20098?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/groupby.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ3JvdXBieS5weQ==) | `92.14% <ø> (ø)` | |
| [pandas/plotting/\_compat.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb21wYXQucHk=) | `62% <0%> (-28.91%)` | :arrow_down: |
| [pandas/io/s3.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL3MzLnB5) | `72.72% <0%> (-13.64%)` | :arrow_down: |
| [pandas/core/arrays/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvYXJyYXlzL2Jhc2UucHk=) | `74.35% <0%> (-13.5%)` | :arrow_down: |
| [pandas/util/\_doctools.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX2RvY3Rvb2xzLnB5) | `0% <0%> (-12.88%)` | :arrow_down: |
| [pandas/io/formats/terminal.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvdGVybWluYWwucHk=) | `16.43% <0%> (-4.55%)` | :arrow_down: |
| [pandas/io/formats/printing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvcHJpbnRpbmcucHk=) | `89.38% <0%> (-3.71%)` | :arrow_down: |
| [pandas/io/html.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2h0bWwucHk=) | `86.6% <0%> (-2.57%)` | :arrow_down: |
| [pandas/core/dtypes/missing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZHR5cGVzL21pc3NpbmcucHk=) | `91.07% <0%> (-2.5%)` | :arrow_down: |
| [pandas/io/formats/format.py](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2Zvcm1hdHMvZm9ybWF0LnB5) | `96.26% <0%> (-1.99%)` | :arrow_down: |
| ... and [98 more](https://codecov.io/gh/pandas-dev/pandas/pull/20098/diff?src=pr&el=tree-more) | |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20098?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20098?src=pr&el=footer). Last update [322dbf4...cf3b3e9](https://codecov.io/gh/pandas-dev/pandas/pull/20098?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

can you rebase this
Thanks @ajdyka !