DOC: update the pandas.DataFrame.replace docstring
- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [ ] 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>`
- [ ] It has been proofread on language by another sprint participant

**Note:** Just did a minor improvement, not a full change!

Still a few verification errors:
- Errors in parameters section
  - Parameter "to_replace" description should start with capital letter
  - Parameter "axis" description should finish with "."
- Examples do not pass tests

```
################################################################################
##################### Docstring (pandas.DataFrame.replace) #####################
################################################################################

Replace values given in 'to_replace' with 'value'.

Values of the DataFrame or a Series are being replaced with
other values. One or several values can be replaced with one
or several values.

Parameters
----------
to_replace : str, regex, list, dict, Series, numeric, or None

    * numeric, str or regex:

        - numeric: numeric values equal to ``to_replace`` will be
          replaced with ``value``
        - str: string exactly matching ``to_replace`` will be replaced
          with ``value``
        - regex: regexs matching ``to_replace`` will be replaced with
          ``value``

    * list of str, regex, or numeric:

        - First, if ``to_replace`` and ``value`` are both lists, they
          **must** be the same length.
        - Second, if ``regex=True`` then all of the strings in **both**
          lists will be interpreted as regexs otherwise they will match
          directly. This doesn't matter much for ``value`` since there
          are only a few possible substitution regexes you can use.
        - str, regex and numeric rules apply as above.

    * dict:

        - Dicts can be used to specify different replacement values
          for different existing values. For example,
          {'a': 'b', 'y': 'z'} replaces the value 'a' with 'b' and
          'y' with 'z'. To use a dict in this way the ``value``
          parameter should be ``None``.
        - For a DataFrame a dict can specify that different values
          should be replaced in different columns. For example,
          {'a': 1, 'b': 'z'} looks for the value 1 in column 'a' and
          the value 'z' in column 'b' and replaces these values with
          whatever is specified in ``value``. The ``value`` parameter
          should not be ``None`` in this case. You can treat this as a
          special case of passing two lists except that you are
          specifying the column to search in.
        - For a DataFrame nested dictionaries, e.g.,
          {'a': {'b': np.nan}}, are read as follows: look in column 'a'
          for the value 'b' and replace it with NaN. The ``value``
          parameter should be ``None`` to use a nested dict in this
          way. You can nest regular expressions as well. Note that
          column names (the top-level dictionary keys in a nested
          dictionary) **cannot** be regular expressions.

    * None:

        - This means that the ``regex`` argument must be a string,
          compiled regular expression, or list, dict, ndarray or Series
          of such elements. If ``value`` is also ``None`` then this
          **must** be a nested dictionary or ``Series``.

    See the examples section for examples of each of these.
value : scalar, dict, list, str, regex, default None
    Value to replace any values matching ``to_replace`` with.
    For a DataFrame a dict of values can be used to specify which
    value to use for each column (columns not in the dict will not be
    filled). Regular expressions, strings and lists or dicts of such
    objects are also allowed.
inplace : boolean, default False
    If True, in place. Note: this will modify any
    other views on this object (e.g. a column from a DataFrame).
    Returns the caller if this is True.
limit : int, default None
    Maximum size gap to forward or backward fill.
regex : bool or same types as ``to_replace``, default False
    Whether to interpret ``to_replace`` and/or ``value`` as regular
    expressions. If this is ``True`` then ``to_replace`` *must* be a
    string. Alternatively, this could be a regular expression or a
    list, dict, or array of regular expressions in which case
    ``to_replace`` must be ``None``.
method : string, optional, {'pad', 'ffill', 'bfill'}, default is 'pad'
    The method to use when for replacement, when ``to_replace`` is a
    scalar, list or tuple and ``value`` is None.
axis : None
    Deprecated.

    .. versionchanged:: 0.23.0
        Added to DataFrame

See Also
--------
DataFrame.fillna : Fill NA/NaN values
DataFrame.where : Replace values based on boolean condition

Returns
-------
DataFrame
    Some values have been substituted for new values.

Raises
------
AssertionError
    * If ``regex`` is not a ``bool`` and ``to_replace`` is not
      ``None``.
TypeError
    * If ``to_replace`` is a ``dict`` and ``value`` is not a ``list``,
      ``dict``, ``ndarray``, or ``Series``
    * If ``to_replace`` is ``None`` and ``regex`` is not compilable
      into a regular expression or is a list, dict, ndarray, or
      Series.
    * When replacing multiple ``bool`` or ``datetime64`` objects and
      the arguments to ``to_replace`` does not match the type of the
      value being replaced
ValueError
    * If a ``list`` or an ``ndarray`` is passed to ``to_replace`` and
      `value` but they are not the same length.

Notes
-----
* Regex substitution is performed under the hood with ``re.sub``. The
  rules for substitution for ``re.sub`` are the same.
* Regular expressions will only substitute on strings, meaning you
  cannot provide, for example, a regular expression matching floating
  point numbers and expect the columns in your frame that have a
  numeric dtype to be matched. However, if those floating point
  numbers *are* strings, then you can do this.
* This method has *a lot* of options. You are encouraged to experiment
  and play with this method to gain intuition about how it works.

Examples
--------

>>> s = pd.Series([0, 1, 2, 3, 4])
>>> s.replace(0, 5)
0    5
1    1
2    2
3    3
4    4
dtype: int64
>>> df = pd.DataFrame({'A': [0, 1, 2, 3, 4],
...                    'B': [5, 6, 7, 8, 9],
...                    'C': ['a', 'b', 'c', 'd', 'e']})
>>> df.replace(0, 5)
   A  B  C
0  5  5  a
1  1  6  b
2  2  7  c
3  3  8  d
4  4  9  e

>>> df.replace([0, 1, 2, 3], 4)
   A  B  C
0  4  5  a
1  4  6  b
2  4  7  c
3  4  8  d
4  4  9  e
>>> df.replace([0, 1, 2, 3], [4, 3, 2, 1])
   A  B  C
0  4  5  a
1  3  6  b
2  2  7  c
3  1  8  d
4  4  9  e
>>> s.replace([1, 2], method='bfill')
0    0
1    3
2    3
3    3
4    4
dtype: int64

>>> df.replace({0: 10, 1: 100})
     A  B  C
0   10  5  a
1  100  6  b
2    2  7  c
3    3  8  d
4    4  9  e
>>> df.replace({'A': 0, 'B': 5}, 100)
     A    B  C
0  100  100  a
1    1    6  b
2    2    7  c
3    3    8  d
4    4    9  e
>>> df.replace({'A': {0: 100, 4: 400}})
     A  B  C
0  100  5  a
1    1  6  b
2    2  7  c
3    3  8  d
4  400  9  e

>>> df = pd.DataFrame({'A': ['bat', 'foo', 'bait'],
...                    'B': ['abc', 'bar', 'xyz']})
>>> df.replace(to_replace=r'^ba.$', value='new', regex=True)
      A    B
0   new  abc
1   foo  new
2  bait  xyz
>>> df.replace({'A': r'^ba.$'}, {'A': 'new'}, regex=True)
      A    B
0   new  abc
1   foo  bar
2  bait  xyz
>>> df.replace(regex=r'^ba.$', value='new')
      A    B
0   new  abc
1   foo  new
2  bait  xyz
>>> df.replace(regex={r'^ba.$':'new', 'foo':'xyz'})
      A    B
0   new  abc
1   xyz  new
2  bait  xyz
>>> df.replace(regex=[r'^ba.$', 'foo'], value='new')
      A    B
0   new  abc
1   new  new
2  bait  xyz

Note that when replacing multiple ``bool`` or ``datetime64`` objects,
the data types in the ``to_replace`` parameter must match the data
type of the value being replaced:

>>> df = pd.DataFrame({'A': [True, False, True],
...                    'B': [False, True, False]})
>>> df.replace({'a string': 'new value', True: False})  # raises
TypeError: Cannot compare types 'ndarray(dtype=bool)' and 'str'

This raises a ``TypeError`` because one of the ``dict`` keys is not of
the correct type for replacement.

Compare the behavior of
``s.replace('a', None)`` and ``s.replace({'a': None})`` to understand
the pecularities of the ``to_replace`` parameter.
``s.replace('a', None)`` is actually equivalent to
``s.replace(to_replace='a', value=None, method='pad')``,
because when ``value=None`` and ``to_replace`` is a scalar, list or
tuple, ``replace`` uses the method parameter to do the replacement.
So this is why the 'a' values are being replaced by 30 in rows 3 and 4
and 'b' in row 6 in this case. However, this behaviour does not occur
when you use a dict as the ``to_replace`` value. In this case, it is
like the value(s) in the dict are equal to the value parameter.

>>> s = pd.Series([10, 20, 30, 'a', 'a', 'b', 'a'])
>>> print(s)
0    10
1    20
2    30
3     a
4     a
5     b
6     a
dtype: object
>>> print(s.replace('a', None))
0    10
1    20
2    30
3    30
4    30
5     b
6     b
dtype: object
>>> print(s.replace({'a': None}))
0      10
1      20
2      30
3    None
4    None
5       b
6    None
dtype: object

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

Errors found:
        Errors in parameters section
                Parameter "to_replace" description should start with capital letter
                Parameter "axis" description should finish with "."
        Examples do not pass tests

################################################################################
################################### Doctests ###################################
################################################################################

**********************************************************************
Line 229, in pandas.DataFrame.replace
Failed example:
    df.replace({'a string': 'new value', True: False})  # raises
Exception raised:
    Traceback (most recent call last):
      File "C:\Users\thisi\AppData\Local\conda\conda\envs\pandas_dev\lib\doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.DataFrame.replace[17]>", line 1, in <module>
        df.replace({'a string': 'new value', True: False})  # raises
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\frame.py", line 3136, in replace
        method=method, axis=axis)
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\generic.py", line 5208, in replace
        limit=limit, regex=regex)
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\frame.py", line 3136, in replace
        method=method, axis=axis)
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\generic.py", line 5257, in replace
        regex=regex)
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\internals.py", line 3696, in replace_list
        masks = [comp(s) for i, s in enumerate(src_list)]
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\internals.py", line 3696, in <listcomp>
        masks = [comp(s) for i, s in enumerate(src_list)]
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\internals.py", line 3694, in comp
        return _maybe_compare(values, getattr(s, 'asm8', s), operator.eq)
      File "C:\Users\thisi\Documents\GitHub\pandas\pandas\core\internals.py", line 5122, in _maybe_compare
        b=type_names[1]))
    TypeError: Cannot compare types 'ndarray(dtype=bool)' and 'str'
```
