DOC: improve doc string for .aggregate and .transform
State: closed

Since #21224, operations using ``axis=1`` in df.aggregate and df.transform now work the same as when axis=0.

This PR updates the methods' doc strings to reflect the new reality. For example, we can now pass a dict to DataFrame.agg/transform when ``axis=1`` also, and ``DataFrame.transform`` now has an ``axis`` parameter.

There's a minor API change, as ``Series.transform`` should have a ``axis=0`` parameter to have the same API as ``Series.aggregate``.

Also some related minor clarifications.

Labels:
name: Docs

Comments:
Hello @topper-123! Thanks for submitting the PR.

 - There are no PEP8 issues in the file [`pandas/core/frame.py`](https://github.com/topper-123/pandas/blob/540aa3c8da8077ddac1a09d08273c82a1f69591b/pandas/core/frame.py) !

 - There are no PEP8 issues in the file [`pandas/core/generic.py`](https://github.com/topper-123/pandas/blob/540aa3c8da8077ddac1a09d08273c82a1f69591b/pandas/core/generic.py) !

 - There are no PEP8 issues in the file [`pandas/core/series.py`](https://github.com/topper-123/pandas/blob/540aa3c8da8077ddac1a09d08273c82a1f69591b/pandas/core/series.py) !


# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22641?src=pr&el=h1) Report
> Merging [#22641](https://codecov.io/gh/pandas-dev/pandas/pull/22641?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/996f361f8e6986ea1c65ccb164a4c585e1f4a027?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #22641      +/-   ##
==========================================
+ Coverage   92.16%   92.16%   +<.01%     
==========================================
  Files         169      169              
  Lines       50708    50716       +8     
==========================================
+ Hits        46734    46742       +8     
  Misses       3974     3974
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.57% <100%> (ø)` | :arrow_up: |
| #single | `42.35% <77.77%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/22641?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/22641/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.19% <100%> (ø)` | :arrow_up: |
| [pandas/core/series.py](https://codecov.io/gh/pandas-dev/pandas/pull/22641/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc2VyaWVzLnB5) | `93.76% <100%> (+0.03%)` | :arrow_up: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/22641/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `96.67% <100%> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/22641?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/22641?src=pr&el=footer). Last update [996f361...b9d0dd3](https://codecov.io/gh/pandas-dev/pandas/pull/22641?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

all tests have passed. Is this ok?
@datapythonista , I'm not familiar with ``ci/doctest.sh``. Are you saying I should remove the two ``-transform`` parameters from that file?

Wrt. other stuff, I've made various changes according to the comments (great comments BTW).

EDIT: BTW, I ran ``./scripts/validate_docstrings.py pandas.Series.transform`` and it caught a few issues, that I've corrected in the latest commit. so if ``ci/doctest.sh`` catches issues like that, I assume I should delete the ``-transform-`` parameters, right? (haven't done it atm).
@topper-123 at the moment we don't do the validation of docstrings in the CI (there are too many failing, and the script also reports false positives). the `ci/doctest.sh` just runs the doctests in the examples from the CI (so far for Series and DataFrame method only I think). As there are still many failing, they are skipped in `doctest.sh`. So, yes, my point was that as you know fixed the doctests on those docstrings, we don't need to skip them anymore from the doctests, and any further change in the examples in the future, the CI will validate that we don't break them.
I think all is done now.
thanks @topper-123