DOC: Fix the docstring of join in pandas/core/frame.py

[datapythonista]

pandas docstring are expected to follow the format defined in https://pandas.pydata.org/pandas-docs/stable/contributing_docstring.html

This includes among other things:

• There is a short description fitting in one line (there can be a longer one after that).
• The description of the parameters, the returns section, and the see also items, starts with a capital letter and ends with a period.
• In the Return section there is no name before the type (e.g. transformed : Series) but just the type (e.g. Series) in the first line.
• The examples are valid PEP-8 code, and when executed, they produce the shown input.

We should make the required adjustments in the docstring of the function join in pandas/core/frame.py.

We should validate the docstring with our validator (which does not validate all the formats, but some):

• ./scripts/validate_docstrings.py pandas.DataFrame.join

And we should validate the PEP-8 of the examples (note that the next command will validate the PEP-8 of all examples, just make sure that none of the shown is in the function being addressed, the rest will be fixed in separate issues):

• flake8 --doctests pandas/core/frame.py

[JustinZhengBC]

Has anyone else claimed this issue? If not, I'd like to try it.