DOC: clarify "inplace"-ness of DataFrame.setitem (#51328)

Author: loicdiridollou

pandas/core/frame.py

@@ -3870,23 +3870,27 @@ def _get_value(self, index, col, takeable: bool = False) -> Scalar:
 
  def isetitem(self, loc, value) -> None:
  """
- Set the given value in the column with position 'loc'.
+ Set the given value in the column with position `loc`.
 
- This is a positional analogue to __setitem__.
+ This is a positional analogue to ``__setitem__``.
 
  Parameters
  ----------
  loc : int or sequence of ints
+ Index position for the column.
  value : scalar or arraylike
+ Value(s) for the column.
 
  Notes
  -----
- 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.
-
- In cases where `frame.columns` is unique, this is equivalent to
- `frame[frame.columns[i]] = value`.
+ ``frame.isetitem(loc, value)`` is an in-place method as it will
+ modify the DataFrame in place (not returning a new object). In contrast to
+ ``frame.iloc[:, i] = value`` which will try to update the existing values in
+ place, ``frame.isetitem(loc, value)`` will not update the values of the column
+ itself in place, it will instead insert a new array.
+
+ In cases where ``frame.columns`` is unique, this is equivalent to
+ ``frame[frame.columns[i]] = value``.
  """
  if isinstance(value, DataFrame):
  if is_scalar(loc):