DOC: explain the mode.chained_assignment option

Author: sietse

doc/source/indexing.rst

@@ -1833,15 +1833,22 @@ 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.
-
-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.
+When using chained indexing, the order may determine whether a copy is returned
+or not.
+
+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``, which can take
+the values ``['raise', 'warn', None]``. ``'raise'`` will convert the warnings
+to a ``SettingWithCopyException`` you have to deal with; ``warn``, the default,
+raises a warning, and ``None`` will suppress the warnings entirely.
 
 .. ipython:: python
    :okwarning:

doc/source/options.rst

@@ -417,9 +417,9 @@ io.hdf.dropna_table                 True         drop ALL nan rows when appendin
 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         '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,