DOC: update the DataFrame.mode method docstring
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.mode)  ######################
################################################################################

Get the mode(s) of each element along the axis selected.

Adds a row for each mode per label, filling gaps with NaN.

Parameters
----------
axis : {0 or 'index', 1 or 'columns'}, default 0
    The axis to iterate over while searching for the mode.
    To find the mode for each column, iterate over rows (``axis=0``
    default behaviour).
    To find the mode for each row, iterate over columns (``axis=1``).
numeric_only : boolean, default False
    If True, only apply to numeric dimensions.

Returns
-------
modes : DataFrame (sorted)
    A DataFrame containing the modes
    If ``axis=0``, there will be one column per column in the original
    DataFrame, with as many rows as there are modes.
    If ``axis=1``, there will be one row per row in the original
    DataFrame, with as many columns as there are modes.

Notes
-----
There may be multiple values returned for the selected
axis (when more than one item share the maximum frequency), which is
the reason why a dataframe is returned. If you want to impute missing
values with the mode in a dataframe ``df``, you can just do this:
``df.fillna(df.mode().iloc[0])``.

See Also
--------
Series.mode : Return the highest frequency value in a Series.
Series.value_counts : Returns a Series with all occuring values as
    indices and the number of occurences as values.

Examples
--------

``mode`` returns a DataFrame with multiple rows if there is more than
one mode. Missing entries are imputed with NaN.

>>> grades = pd.DataFrame({
...     'Science': [80, 70, 80, 75, 80, 75, 85, 90, 80, 70],
...     'Math': [70, 70, 75, 75, 80, 80, 85, 85, 90, 90]
... })
>>> grades.apply(lambda x: x.value_counts())
    Science  Math
70        2     2
75        2     2
80        4     2
85        1     2
90        1     2
>>> grades.mode()
   Science  Math
0     80.0    70
1      NaN    75
2      NaN    80
3      NaN    85
4      NaN    90

Use ``axis=1`` to apply mode over columns (get the mode of each row).

>>> student_grades = pd.DataFrame.from_dict({
...     'Alice': [80, 85, 90, 85, 95],
...     'Bob': [70, 80, 80, 75, 90]
... }, 'index')
>>> student_grades
        0   1   2   3   4
Alice  80  85  90  85  95
Bob    70  80  80  75  90
>>> student_grades.mode(axis=1)
        0
Alice  85
Bob    80

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.mode" 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.

