Help: Document more use cases for CMAKE_POLICY_DEFAULT_CMPNNNN

1 files changed, 13 insertions, 6 deletions

diff --git a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst
index 43582be94d..d643fb8df1 100644
--- a/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst
+++ b/Help/variable/CMAKE_POLICY_DEFAULT_CMPNNNN.rst
@@ -9,9 +9,16 @@ the given version unset.  Set ``CMAKE_POLICY_DEFAULT_CMP<NNNN>`` to ``OLD``
 or ``NEW`` to specify the default for policy ``CMP<NNNN>``, where ``<NNNN>``
 is the policy number.
 
-This variable should not be set by a project in CMake code; use
-:command:`cmake_policy(SET)` instead.  Users running CMake may set this
-variable in the cache (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``)
-to set a policy not otherwise set by the project.  Set to ``OLD`` to quiet a
-policy warning while using old behavior or to ``NEW`` to try building the
-project with new behavior.
+This variable should not be set by a project in CMake code as a way to
+set its own policies; use :command:`cmake_policy(SET)` instead.  This
+variable is meant to externally set policies for which a project has
+not itself been updated:
+
+* Users running CMake may set this variable in the cache
+  (e.g. ``-DCMAKE_POLICY_DEFAULT_CMP<NNNN>=<OLD|NEW>``).  Set it to ``OLD``
+  to quiet a policy warning while using old behavior or to ``NEW`` to
+  try building the project with new behavior.
+
+* Projects may set this variable before a call to :command:`add_subdirectory`
+  that adds a third-party project in order to set its policies without
+  modifying third-party code.