Merge topic 'autogen-cmp0071-warning'

ff6a5125 Autogen: Doc: Add examples to the SKIP_AUTO* documentations
8831818f Autogen: Doc: Update CMP0071 description
b0775c75 Autogen: Offer solution for CMP0071 in warning message

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !1322

5 files changed, 61 insertions, 17 deletions

diff --git a/Help/policy/CMP0071.rst b/Help/policy/CMP0071.rst
index 61f14dc..ee33aa1 100644
--- a/Help/policy/CMP0071.rst
+++ b/Help/policy/CMP0071.rst
@@ -4,16 +4,15 @@ CMP0071
 Let :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process
 :prop_sf:`GENERATED` files.
 
-CMake 3.10 and newer process regular *and* :prop_sf:`GENERATED` source files
-in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
-In CMake 3.9 and lower, only regular source files were processed in
-:prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`,
-:prop_sf:`GENERATED` source files were ignored.
+Since version 3.10, CMake processes **regular** and :prop_sf:`GENERATED`
+source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
+In earlier CMake versions, only **regular** source files were processed.
+:prop_sf:`GENERATED` source files were ignored silently.
 
-This policy affects how :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` process
-source files that are :prop_sf:`GENERATED`.
+This policy affects how source files that are :prop_sf:`GENERATED`
+get treated in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
 
-The ``OLD`` behavior for this policy is to *ignore* :prop_sf:`GENERATED`
+The ``OLD`` behavior for this policy is to ignore :prop_sf:`GENERATED`
 source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`.
 
 The ``NEW`` behavior for this policy is to process :prop_sf:`GENERATED`
@@ -21,10 +20,19 @@ source files in :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` just like regular
 source files.
 
 .. note::
-  To exclude source files from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC`
-  processing, the boolean source file properties
-  :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` and :prop_sf:`SKIP_AUTOGEN`
-  can be set accordingly.
+
+  To silence the CMP0071 warning source files can be excluded from
+  :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the
+  source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or
+  :prop_sf:`SKIP_AUTOGEN`.
+
+Source skip example::
+
+  # ...
+  set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON)
+  set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON)
+  set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON)
+  # ...
 
 This policy was introduced in CMake version 3.10.  CMake version
 |release| warns when the policy is not set and uses ``OLD`` behavior.
diff --git a/Help/prop_sf/SKIP_AUTOGEN.rst b/Help/prop_sf/SKIP_AUTOGEN.rst
index 6bf2409..f31185a 100644
--- a/Help/prop_sf/SKIP_AUTOGEN.rst
+++ b/Help/prop_sf/SKIP_AUTOGEN.rst
@@ -4,5 +4,14 @@ SKIP_AUTOGEN
 Exclude the source file from :prop_tgt:`AUTOMOC`, :prop_tgt:`AUTOUIC` and
 :prop_tgt:`AUTORCC` processing (for Qt projects).
 
-For finer control see :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` and
-:prop_sf:`SKIP_AUTORCC`.
+For finer exclusion control see :prop_sf:`SKIP_AUTOMOC`,
+:prop_sf:`SKIP_AUTOUIC` and :prop_sf:`SKIP_AUTORCC`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.h PROPERTY SKIP_AUTOGEN ON)
+  # ...
diff --git a/Help/prop_sf/SKIP_AUTOMOC.rst b/Help/prop_sf/SKIP_AUTOMOC.rst
index 2245ca6..a929448 100644
--- a/Help/prop_sf/SKIP_AUTOMOC.rst
+++ b/Help/prop_sf/SKIP_AUTOMOC.rst
@@ -3,4 +3,13 @@ SKIP_AUTOMOC
 
 Exclude the source file from :prop_tgt:`AUTOMOC` processing (for Qt projects).
 
-For broader control see :prop_sf:`SKIP_AUTOGEN`
+For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.h PROPERTY SKIP_AUTOMOC ON)
+  # ...
diff --git a/Help/prop_sf/SKIP_AUTORCC.rst b/Help/prop_sf/SKIP_AUTORCC.rst
index 394d8f8..bccccfc 100644
--- a/Help/prop_sf/SKIP_AUTORCC.rst
+++ b/Help/prop_sf/SKIP_AUTORCC.rst
@@ -3,4 +3,13 @@ SKIP_AUTORCC
 
 Exclude the source file from :prop_tgt:`AUTORCC` processing (for Qt projects).
 
-For broader control see :prop_sf:`SKIP_AUTOGEN`
+For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.qrc PROPERTY SKIP_AUTORCC ON)
+  # ...
diff --git a/Help/prop_sf/SKIP_AUTOUIC.rst b/Help/prop_sf/SKIP_AUTOUIC.rst
index 50f78ef..4eda726 100644
--- a/Help/prop_sf/SKIP_AUTOUIC.rst
+++ b/Help/prop_sf/SKIP_AUTOUIC.rst
@@ -3,4 +3,13 @@ SKIP_AUTOUIC
 
 Exclude the source file from :prop_tgt:`AUTOUIC` processing (for Qt projects).
 
-For broader control see :prop_sf:`SKIP_AUTOGEN`
+For broader exclusion control see :prop_sf:`SKIP_AUTOGEN`.
+
+EXAMPLE
+^^^^^^^
+
+.. code-block:: cmake
+
+  # ...
+  set_property(SOURCE file.h PROPERTY SKIP_AUTOUIC ON)
+  # ...