DOC: Update the DataFrame.join() 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

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
###################### Docstring (pandas.DataFrame.join)  ######################
################################################################################

Join columns with other DataFrame either on index or a key
column.

Efficiently Join multiple DataFrame objects by index at once by
passing a list.

Parameters
----------
other : DataFrame, Series with name field set, or list of DataFrame
    Index should be similar to one of the columns in this one. If a
    Series is passed, its name attribute must be set, and that will be
    used as the column name in the resulting joined DataFrame.
on : name, tuple/list of names, or array-like
    Column or index level name(s) in the caller to join on the index
    in `other`, otherwise joins index-on-index. If multiple
    values given, the `other` DataFrame must have a MultiIndex. Can
    pass an array as the join key if it is not already contained in
    the calling DataFrame. Like an Excel VLOOKUP operation.
how : {'left', 'right', 'outer', 'inner'}, default: 'left'
    How to handle the operation of the two objects.

    * left: use calling frame's index (or column if on is specified).
    * right: use other frame's index.
    * outer: form union of calling frame's index (or column if on is
      specified) with other frame's index, and sort it
      lexicographically.
    * inner: form intersection of calling frame's index (or column if
      on is specified) with other frame's index, preserving the order
      of the calling's one.
lsuffix : string
    Suffix to use from left frame's overlapping columns.
rsuffix : string
    Suffix to use from right frame's overlapping columns.
sort : boolean, default False
    Order result DataFrame lexicographically by the join key. If False,
    the order of the join key depends on the join type (how keyword).

Notes
-----
The on, lsuffix, and rsuffix options are not supported when passing
a list of DataFrame objects.

Support for specifying index levels as the `on` parameter was added
in version 0.23.0.

Examples
--------
>>> caller = pd.DataFrame({'A': ['A0', 'A1', 'A2', 'A3', 'A4', 'A5'],
...                      'key': ['K0', 'K1', 'K2', 'K3', 'K4', 'K5']})

>>> caller
    A key
0  A0  K0
1  A1  K1
2  A2  K2
3  A3  K3
4  A4  K4
5  A5  K5

>>> other = pd.DataFrame({'B': ['B0', 'B1', 'B2'],
...                       'key': ['K0', 'K1', 'K2']})

>>> other
    B key
0  B0  K0
1  B1  K1
2  B2  K2

Join DataFrames using their indexes.

>>> caller.join(other, lsuffix='_caller', rsuffix='_other')
    A key_caller    B key_other
0  A0         K0   B0        K0
1  A1         K1   B1        K1
2  A2         K2   B2        K2
3  A3         K3  NaN       NaN
4  A4         K4  NaN       NaN
5  A5         K5  NaN       NaN

If we want to join using the key columns, we need to set key to be
the index in both caller and other. The joined DataFrame will have
key as its index.

>>> caller.set_index('key').join(other.set_index('key'))
  A    B
key
K0   A0   B0
K1   A1   B1
K2   A2   B2
K3   A3  NaN
K4   A4  NaN
K5   A5  NaN

Another option to join using the key columns is to use the on
parameter. DataFrame.join always uses other's index but we can use any
column in the caller. This method preserves the original caller's
index in the result.

>>> caller.join(other.set_index('key'), on='key')
    A key    B
0  A0  K0   B0
1  A1  K1   B1
2  A2  K2   B2
3  A3  K3  NaN
4  A4  K4  NaN
5  A5  K5  NaN

See also
--------
DataFrame.merge : For column(s)-on-columns(s) operations

Returns
-------
joined : DataFrame

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.join" correct. :)
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.


Labels:
name: Docs
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20195?src=pr&el=h1) Report
> :exclamation: No coverage uploaded for pull request base (`master@0d86742`). [Click here to learn what that means](https://docs.codecov.io/docs/error-reference#section-missing-base-commit).
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff            @@
##             master   #20195   +/-   ##
=========================================
  Coverage          ?    91.7%           
=========================================
  Files             ?      150           
  Lines             ?    49152           
  Branches          ?        0           
=========================================
  Hits              ?    45074           
  Misses            ?     4078           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.08% <ø> (?)` | |
| #single | `41.84% <ø> (?)` | |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20195?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20195/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.18% <ø> (ø)` | |

------

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

I have made the changes. Waiting for reviews.
@kantologist can you please restore the original examples, as per previous review?
Closing as stale.