DOC: Clarify output of diff (returned type and possible overflow)
State: closed

- [x] closes #28909
- [x] tests passed
- [x] passes `black pandas`
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] note about dtype in `diff` in Dataframa and Series


Labels:
name: Docs
name: Numeric Operations
description: Arithmetic, Comparison, and Logical operations

Comments:
Thanks for the PR. I don't understand the comments though - can you maybe provide code for what you are trying to express?
Thanks for working on this @mproszewska. Agree with @WillAyd, I don't understand what's the comment trying to explain. I can read what's the problem in the issue, but I don't think the added comment is helping users understand. Can you give it another try?
Hello @mproszewska! Thanks for updating this PR. We checked the lines you've touched for [PEP 8](https://www.python.org/dev/peps/pep-0008) issues, and found:





There are currently no PEP 8 issues detected in this Pull Request. Cheers! :beers: 

##### Comment last updated at 2020-05-31 13:11:56 UTC
Thanks @mproszewska. Can you use another variable `{examples}` for the examples, instead of using `Appender` (we want to deprecate `Appender` and use `doc` instead).

Also, you've got conflicts. And if you can run `scripts/validate_docstrings.py pandas.Series.diff` and same for the other docstring, to make sure that they render as you expect, and that no error is reported, that would be great.

Thanks! 
> Also, you've got conflicts. And if you can run `scripts/validate_docstrings.py pandas.Series.diff` and same for the other docstring, to make sure that they render as you expect, and that no error is reported, that would be great.

I can't run this script. I have numpydoc installed but I keep getting
```
Traceback (most recent call last):
  File "scripts/validate_docstrings.py", line 50, in <module>
    from numpydoc.validate import validate, Docstring  # noqa: E402 isort:skip
ModuleNotFoundError: No module named 'numpydoc.validate'
```

I checked changed docs with `help(pd.Series.diff)` and they seemed fine.


You need to install the development version of numpydoc. It's in `environment.yml`. If you're using conda and installing things in the recommended way, a simple `conda env update` in the root directory of pandas should get you the right version.
Thanks @mproszewska 

Can you run `./scripts/validate_docstrings.py pandas.DataFrame.diff` and make sure it doesn't report any error please?

And you'll have to run `black` to fix the CI. Thanks!
`validate_docstrings` does not report any errors.
@mproszewska can you see if you can get the CI passing
`test_diff` was checking stacklevel of warning produced by `diff`. After my changes in documentation warning was raised in `_decorators.py` file instead of `test_algos.py`. I changed test so that stacklevel is not checked. I'm not sure if that's the best idea, but I couldn't find any other way.
I changed stacklevel. Everything should be fine now.
@mproszewska can you merge master and ping on green.

@datapythonista over to you.
Thanks @mproszewska, great PR.

Can you have a look at https://pandas.pydata.org/docs/dev/reference/api/pandas.DataFrame.diff.html when it's updated, and see that everything looks as expected please?