DOC: clarify "inplace"-ness of DataFrame.setitem

[jorisvandenbossche]

The docstring of DataFrame.isetitem (https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.isetitem.html) has the following quote:

Unlike frame.iloc[:, i] = value, frame.isetitem(loc, value) will never try to set the values in place, but will always insert a new array.

But the docstring is actually confusing here, because it is an inplace method in the sense that it is updating the object inplace (and not returning a new object like most methods). It's only not inplace in the sense that it will not update values inplace.

Originally posted by @jorisvandenbossche in #51296 (comment)

[jorisvandenbossche]

We should also fix the formatting in that docstring to properly show the inline code snippets as code.

[loicdiridollou]

I did a few experiments on my side to better understand the behavior and this is how we could rephrase it:

frame.isetimtem(loc, value) is an in-place method as it will modify the frame in place (not returning a new object) but it will not update the values of the column itself, it will instead insert a new array.

I will address the code snippets in the meantime. Let me know if you agree with the rephrasing above, I can make another proposal if needed.

[loicdiridollou]

take