Autogen: Update <ORIGIN>_autogen target documentation

1 files changed, 23 insertions, 15 deletions

diff --git a/Help/manual/cmake-qt.7.rst b/Help/manual/cmake-qt.7.rst
index 724d8ec2a8..0382794626 100644
--- a/Help/manual/cmake-qt.7.rst
+++ b/Help/manual/cmake-qt.7.rst
@@ -44,14 +44,10 @@ Qt Build Tools
 
 Qt relies on some bundled tools for code generation, such as ``moc`` for
 meta-object code generation, ``uic`` for widget layout and population,
-and ``rcc`` for virtual filesystem content generation.  These tools may be
+and ``rcc`` for virtual file system content generation.  These tools may be
 automatically invoked by :manual:`cmake(1)` if the appropriate conditions
 are met.  The automatic tool invocation may be used with both Qt 4 and Qt 5.
 
-The tools are executed as part of a synthesized custom target generated by
-CMake.  Target dependencies may be added to that custom target by adding them
-to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
-
 AUTOMOC
 ^^^^^^^
 
@@ -214,19 +210,31 @@ overrides options from the :prop_tgt:`AUTORCC_OPTIONS` target property.
 Source files can be excluded from :prop_tgt:`AUTORCC` processing by
 enabling :prop_sf:`SKIP_AUTORCC` or the broader :prop_sf:`SKIP_AUTOGEN`.
 
+The ``<ORIGIN>_autogen`` target
+===============================
+
+The ``moc`` and ``uic`` tools are executed as part of a synthesized
+``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` generated by
+CMake.  By default that ``<ORIGIN>_autogen`` target inherits the dependencies
+of the ``<ORIGIN>`` target (see :prop_tgt:`AUTOGEN_ORIGIN_DEPENDS`).
+Target dependencies may be added to the ``<ORIGIN>_autogen`` target by adding
+them to the :prop_tgt:`AUTOGEN_TARGET_DEPENDS` target property.
+
 Visual Studio Generators
 ========================
 
-When using the :manual:`Visual Studio generators <cmake-generators(7)>`,
-CMake uses a ``PRE_BUILD`` :command:`custom command <add_custom_command>` for
-:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
-If the :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing depends on files,
-a :command:`custom target <add_custom_target>` is used instead.
-This happens when
-
-- The origin target depends on :prop_sf:`GENERATED` files which aren't excluded
-  from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by :prop_sf:`SKIP_AUTOMOC`,
-  :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN` or :policy:`CMP0071`
+When using the :manual:`Visual Studio generators <cmake-generators(7)>`, CMake
+generates a ``PRE_BUILD`` :command:`custom command <add_custom_command>`
+instead of the ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>`
+(for :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`).
+This isn't always possible though and
+an ``<ORIGIN>_autogen`` :command:`custom target <add_custom_target>` is used,
+when either
+
+- the ``<ORIGIN>`` target depends on :prop_sf:`GENERATED` files which aren't
+  excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` by
+  :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC`, :prop_sf:`SKIP_AUTOGEN`
+  or :policy:`CMP0071`
 - :prop_tgt:`AUTOGEN_TARGET_DEPENDS` lists a source file
 
 qtmain.lib on Windows