GENERATED: Improve the documentation of the GENERATED file property

1 files changed, 19 insertions, 4 deletions

diff --git a/Help/prop_sf/GENERATED.rst b/Help/prop_sf/GENERATED.rst
index a3aa127..d430ee2 100644
--- a/Help/prop_sf/GENERATED.rst
+++ b/Help/prop_sf/GENERATED.rst
@@ -1,8 +1,23 @@
 GENERATED
 ---------
 
-Is this source file generated as part of the build process.
+Is this source file generated as part of the build or CMake process.
 
-If a source file is generated by the build process CMake will handle
-it differently in terms of dependency checking etc.  Otherwise having
-a non-existent source file could create problems.
+Tells the internal CMake engine that a source file is generated by an outside
+process such as another build step, or the execution of CMake itself. This
+information is then used to exempt the file from any existence or validity
+checks. Generated files are created by the execution of commands such as
+:command:`add_custom_command` and :command:`file(GENERATE)`.
+
+When a generated file created by an :command:`add_custom_command` command
+is explicitly listed as a source file for any target in the same
+directory scope (which usually means the same ``CMakeLists.txt`` file),
+CMake will automatically create a dependency to make sure the file is
+generated before building that target.
+
+Generated sources may be hidden in some IDE tools, while in others they might
+be shown. For the special case of sources generated by CMake's :prop_tgt:`AUTOMOC`
+or :prop_tgt:`AUTORCC` functionality, the :prop_gbl:`AUTOGEN_SOURCE_GROUP`,
+:prop_gbl:`AUTOMOC_SOURCE_GROUP` and :prop_gbl:`AUTORCC_SOURCE_GROUP` target
+properties may influence where the generated sources are grouped in the project's
+file lists.