DOC: explain the mode.chained_assignment option (#18635)

Author: sietse

doc/source/indexing.rst

@@ -1833,15 +1833,27 @@ that you've done this:
 
 Yikes!
 
+.. _indexing.evaluation_order:
+
 Evaluation order matters
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Furthermore, in chained expressions, the order may determine whether a copy is returned or not.
-If an expression will set values on a copy of a slice, then a ``SettingWithCopy``
-warning will be issued.
+When you use chained indexing, the order and type of the indexing operation
+partially determine whether the result is a slice into the original object, or
+a copy of the slice.
+
+Pandas has the ``SettingWithCopyWarning`` because assigning to a copy of a
+slice is frequently not intentional, but a mistake caused by chained indexing
+returning a copy where a slice was expected.
+
+If you would like pandas to be more or less trusting about assignment to a
+chained indexing expression, you can set the :ref:`option <options>`
+``mode.chained_assignment`` to one of these values:
 
-You can control the action of a chained assignment via the option ``mode.chained_assignment``,
-which can take the values ``['raise','warn',None]``, where showing a warning is the default.
+* ``'warn'``, the default, means a ``SettingWithCopyWarning`` is printed.
+* ``'raise'`` means pandas will raise a ``SettingWithCopyException``
+  you have to deal with.
+* ``None`` will suppress the warnings entirely.
 
 .. ipython:: python
    :okwarning:

doc/source/options.rst

@@ -417,9 +417,10 @@ io.hdf.dropna_table                     True         drop ALL nan rows when appe
 io.parquet.engine                       None         The engine to use as a default for
                                                      parquet reading and writing. If None
                                                      then try 'pyarrow' and 'fastparquet'
-mode.chained_assignment                 warn         Raise an exception, warn, or no
-                                                     action if trying to use chained
-                                                     assignment, The default is warn
+mode.chained_assignment                 warn         Controls ``SettingWithCopyWarning``: 
+                                                     'raise', 'warn', or None. Raise an
+                                                     exception, warn, or no action if
+                                                     trying to use :ref:`chained assignment <indexing.evaluation_order>`.
 mode.sim_interactive                    False        Whether to simulate interactive mode
                                                      for purposes of testing.
 mode.use_inf_as_na                      False        True means treat None, NaN, -INF,