DOC: Updated convert_dtype of Series.apply
State: closed

- [x] closes #39580
- [ ] tests added / passed
- [ ] Ensure all linting tests pass, see [here](https://pandas.pydata.org/pandas-docs/dev/development/contributing.html#code-standards) for how to run them
- [ ] whatsnew entry

This updates the docs for parameter convert_dtype in pandas.Series.apply and adds dtypes for which the original dtype is kept. 


Labels:
name: Docs
name: Apply
description: Apply, Aggregate, Transform, Map

Comments:
Hello @sukriti1! 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 2021-04-16 09:22:45 UTC
Thanks for updating

Hey @rhshadrach  - any thoughts on this? Re-reading this, I think my suggestion wasn't a very good one (besides, it's `._values` that can have `.map`, not the dtype), I don't think internals need describing to users
Do you really expect users to know what an extension array is? Maybe it's my fault, but I have been using pandas on and off for years and never heard of extension arrays. 

If a user wants to know what dtypes are excluded from conversion they will land on [this](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.api.extensions.ExtensionArray.html) page next. Which quite frankly is gibberish if you are not educated in pandas internals.

But even if the user gets past that, they now will have to research which extension arrays have a `map` method and which ones do not.
Hi @mkp-gebensleben - if you read through the discussion, you'll see that I went back on my initial suggestion to mention extension arrays and the map method
@sukriti1 - Are you interested in finishing this up? If not, would you mind if I pushed it over the finish line?
@rhshadrach Sorry for the delay just pushed the changes! Please let me know if there's anymore feedback
Thanks @sukriti1 
@sukriti1 @MarcoGorelli 

https://github.com/pandas-dev/pandas/pull/39941#discussion_r593880146 - As commented there, I think the changes made in the PR are not quite correct. While it seems to me undesirable to list out the behavior for various extension arrays, I don't see another way to have correct documentation.

An alternative would be to change the behavior of the method itself to match the current docstring. I don't know how palatable this would be.
Hey @rhshadrach - is it necessary to list out behaviour for various extension arrays, or would

> Note that for some extension array dtypes, such as Categorical, the dtype is always preserved.

be enough to make it correct without being too long?
I didn't consider that @MarcoGorelli and do think it's better than incorrect documentation (although it really doesn't tell the user what will happen). I am still wondering if it's not possible to make the current documentation (that is now in master) correct and will take a look at this in a few days.
> I didn't consider that @MarcoGorelli and do think it's better than incorrect documentation (although it really doesn't tell the user what will happen). I am still wondering if it's not possible to make the current documentation (that is now in master) correct and will take a look at this in a few days.

Hey @rhshadrach - just checking if you've had further thoughts on this, and what your preference would be