Help: Improve wording of FOLDER-related properties and policies

3 files changed, 25 insertions, 23 deletions

diff --git a/Help/policy/CMP0143.rst b/Help/policy/CMP0143.rst
index 7a7aee7..24fdc27 100644
--- a/Help/policy/CMP0143.rst
+++ b/Help/policy/CMP0143.rst
@@ -5,7 +5,7 @@ CMP0143
 
 :prop_gbl:`USE_FOLDERS` global property is treated as ``ON`` by default.
 
-When using CMake 3.25 and below, :prop_gbl:`USE_FOLDERS` is treated
+When using CMake 3.25 or earlier, :prop_gbl:`USE_FOLDERS` is treated
 as ``OFF`` by default unless projects enable the feature.  For example:
 
 .. code-block:: cmake
@@ -16,15 +16,15 @@ as ``OFF`` by default unless projects enable the feature.  For example:
 
 CMake 3.26 and later prefer to enable the feature by default.
 
+Note that it is the policy setting at the `end` of the top level
+``CMakeLists.txt`` file that matters.  The policy setting applies globally
+to the whole project.
+
 This policy provides compatibility with projects that have not been updated
 to expect enabling of folders.  Enabling folders causes projects to appear
-differently in IDEs.
-
-This policy was introduced in CMake version 3.26.  Use the
+differently in IDEs.  The policy was introduced in CMake version 3.26.  Use the
 :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
 Unlike many policies, CMake version |release| does *not* warn
 when this policy is not set and simply uses ``OLD`` behavior.
-The policy setting must be in scope at the end of the top-level
-``CMakeLists.txt`` file of the project and has global effect.
 
 .. include:: DEPRECATED.txt
diff --git a/Help/prop_gbl/USE_FOLDERS.rst b/Help/prop_gbl/USE_FOLDERS.rst
index f3d7791..6f5a083 100644
--- a/Help/prop_gbl/USE_FOLDERS.rst
+++ b/Help/prop_gbl/USE_FOLDERS.rst
@@ -1,19 +1,17 @@
 USE_FOLDERS
 -----------
 
-Use the :prop_tgt:`FOLDER` target property to organize targets into
-folders.
+Controls whether to use the :prop_tgt:`FOLDER` target property to organize
+targets into folders.  The value of ``USE_FOLDERS`` at the end of the top level
+``CMakeLists.txt`` file is what determines the behavior.
 
 .. versionchanged:: 3.26
 
   CMake treats this property as ``ON`` by default.
   See policy :policy:`CMP0143`.
 
-CMake generators that are capable of organizing into a hierarchy of folders
-use the values of the :prop_tgt:`FOLDER` target property to name those
-folders. (i.e.: ``Visual Studio`` or ``XCode``)
-
-IDE's can also take advantage of this property to organize CMake targets.
-Regardless of generator support.
-
-See also the documentation for the :prop_tgt:`FOLDER` target property.
+Not all CMake generators support recording folder details for targets.
+The :generator:`Xcode` and :ref:`Visual Studio <Visual Studio Generators>`
+generators are examples of generators that do.  Similarly, not all IDEs
+support presenting targets using folder hierarchies, even if the CMake
+generator used provides the necessary information.
diff --git a/Help/prop_tgt/FOLDER.rst b/Help/prop_tgt/FOLDER.rst
index 3155d90..616b962 100644
--- a/Help/prop_tgt/FOLDER.rst
+++ b/Help/prop_tgt/FOLDER.rst
@@ -1,16 +1,20 @@
 FOLDER
 ------
 
-Set the folder name. Use to organize targets in an IDE.
+For IDEs that present targets using a folder hierarchy, this property
+specifies the name of the folder to place the target under.
+To nest folders, use ``FOLDER`` values such as ``GUI/Dialogs`` with ``/``
+characters separating folder levels.  Targets with no ``FOLDER`` property
+will appear as top level entities.  Targets with the same ``FOLDER``
+property value will appear in the same folder as siblings.
 
-Targets with no ``FOLDER`` property will appear as top level entities in
-IDEs like Visual Studio.  Targets with the same ``FOLDER`` property value
-will appear next to each other in a folder of that name.  To nest
-folders, use ``FOLDER`` values such as 'GUI/Dialogs' with '/' characters
-separating folder levels.
+Only some CMake generators honor the ``FOLDER`` property
+(e.g. :generator:`Xcode` or any of the
+:ref:`Visual Studio <Visual Studio Generators>` generators).
+Those generators that don't will simply ignore it.
 
 This property is initialized by the value of the variable
 :variable:`CMAKE_FOLDER` if it is set when a target is created.
 
-The global property :prop_gbl:`USE_FOLDERS` must be set to ON, otherwise
+The global property :prop_gbl:`USE_FOLDERS` must be set to true, otherwise
 the ``FOLDER`` property is ignored.