DOC: update the pandas.Series.where 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.where) ######################
################################################################################

Replace values that don't respect a `cond` condition.

Return an object of same shape as self with entries that
not satisfy a `cond` is True are replaced by `other`.

Parameters
----------
cond : boolean NDFrame, array-like, or callable
    Where `cond` is True, keep the original value. Where
    False, replace with corresponding value from `other`.
    If `cond` is callable, it is computed on the NDFrame and
    should return boolean NDFrame or array. The callable must
    not change input NDFrame (though pandas doesn't check it).

    .. versionadded:: 0.18.1
        A callable can be used as cond.

other : scalar, NDFrame, or callable
    Entries where `cond` is False are replaced with
    corresponding value from `other`.
    If other is callable, it is computed on the NDFrame and
    should return scalar or NDFrame. The callable must not
    change input NDFrame (though pandas doesn't check it).

    .. versionadded:: 0.18.1
        A callable can be used as other.

inplace : boolean, default False
    Whether to perform the operation in place on the data.
axis : int, default None
    Alignment axis if needed.
level : int, default None
    Alignment level if needed.
errors : str, {'raise', 'ignore'}, default `raise`
    Note that currently this parameter won't affect
    the results and will always coerce to a suitable dtype.

    - `raise` : allow exceptions to be raised.
    - `ignore` : suppress exceptions. On error return original object.

try_cast : boolean, default False
    Try to cast the result back to the input type (if possible).
raise_on_error : boolean, default True
    Whether to raise on invalid data types (e.g. trying to where on
    strings).

    .. deprecated:: 0.21.0
    Use `error`.

Returns
-------
wh : same type as caller

Notes
-----
The where method is an application of the if-then idiom. For each
element in the calling DataFrame, if ``cond`` is ``True`` the
element is used; otherwise the corresponding element from the DataFrame
``other`` is used.

The signature for :func:`DataFrame.where` differs from
:func:`numpy.where`. Roughly ``df1.where(m, df2)`` is equivalent to
``np.where(m, df1, df2)``.

For further details and examples see the ``where`` documentation in
:ref:`indexing <indexing.where_mask>`.

See Also
--------
:func:`DataFrame.mask` : Return an object of same shape as self

Examples
--------
>>> s = pd.Series(range(5))
>>> s.where(s > 0)
0    NaN
1    1.0
2    2.0
3    3.0
4    4.0
dtype: float64

>>> s.mask(s > 0)
0    0.0
1    NaN
2    NaN
3    NaN
4    NaN
dtype: float64

>>> s.where(s > 1, 10)
0    10
1    10
2    2
3    3
4    4
dtype: int64

>>> df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=['A', 'B'])
>>> m = df % 3 == 0
>>> df.where(m, -df)
   A  B
0  0 -1
1 -2  3
2 -4 -5
3  6 -7
4 -8  9
>>> df.where(m, -df) == np.where(m, df, -df)
      A     B
0  True  True
1  True  True
2  True  True
3  True  True
4  True  True
>>> df.where(m, -df) == df.mask(~m, -df)
      A     B
0  True  True
1  True  True
2  True  True
3  True  True
4  True  True

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Private classes (['NDFrame']) should not be mentioned in public docstring.
```

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.


Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

- [ ] closes #xxxx
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry


Labels:
name: Docs

Comments:
Hello @simobasso! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on July 08, 2018 at 16:01 Hours UTC
Please, change PR's title to: "DOC: update the pandas.Series.where docstring"
@jbigatti done but FYI 
![schermata 2018-03-10 alle 16 24 16](https://user-images.githubusercontent.com/4202614/37243798-a509bd06-247f-11e8-8c13-a7a72eaad077.png)

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

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

```diff
@@            Coverage Diff            @@
##             master   #20165   +/-   ##
=========================================
  Coverage          ?   91.72%           
=========================================
  Files             ?      150           
  Lines             ?    49152           
  Branches          ?        0           
=========================================
  Hits              ?    45086           
  Misses            ?     4066           
  Partials          ?        0
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <88.88%> (?)` | |
| #single | `41.84% <0%> (?)` | |

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

------

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

Thanks @simobasso !