Help: Clarify behavior of BEFORE with target_compile_options()

1 files changed, 16 insertions, 8 deletions

diff --git a/Help/policy/CMP0101.rst b/Help/policy/CMP0101.rst
index f02bccc881..67810796f5 100644
--- a/Help/policy/CMP0101.rst
+++ b/Help/policy/CMP0101.rst
@@ -3,16 +3,24 @@ CMP0101
 
 .. versionadded:: 3.17
 
-:command:`target_compile_options` now honors ``BEFORE`` keyword in all scopes.
+:command:`target_compile_options` now always honors the ``BEFORE`` keyword.
 
-In CMake 3.16 and below the :command:`target_compile_options` ignores the
-``BEFORE`` keyword in private scope. CMake 3.17 and later honors
-``BEFORE`` keyword in all scopes. This policy provides compatibility for
-projects that have not been updated to expect the new behavior.
+In CMake 3.16 and below, the :command:`target_compile_options` command
+ignores the ``BEFORE`` keyword when inserting items into the
+:prop_tgt:`COMPILE_OPTIONS` target property (``PRIVATE`` and ``PUBLIC``
+items).  CMake 3.17 and later honors the ``BEFORE`` keyword in all cases.
+This policy provides compatibility for projects that have not been updated
+to expect the new behavior.
 
-The ``OLD`` behavior for this policy is to not honor ``BEFORE`` keyword in
-private scope. The ``NEW`` behavior of this policy is to honor
-``BEFORE`` keyword in all scopes.
+The behavior of inserting items into the :prop_tgt:`INTERFACE_COMPILE_OPTIONS`
+target property (``PUBLIC`` and ``INTERFACE`` items) is not affected by this
+policy.  The ``BEFORE`` keyword has always been honored when adding items to
+:prop_tgt:`INTERFACE_COMPILE_OPTIONS`.
+
+The ``OLD`` behavior for this policy is to not honor the ``BEFORE`` keyword
+when inserting into the :prop_tgt:`COMPILE_OPTIONS` property.
+The ``NEW`` behavior for this policy is to honor the ``BEFORE`` keyword in
+all cases.
 
 This policy was introduced in CMake version 3.17.  Use the
 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.