Help: Document relation of properties to the rest of the buildsystem.

4 files changed, 55 insertions, 24 deletions

diff --git a/Help/prop_dir/COMPILE_DEFINITIONS.rst b/Help/prop_dir/COMPILE_DEFINITIONS.rst
index 290d61208c..ab7e7f0581 100644
--- a/Help/prop_dir/COMPILE_DEFINITIONS.rst
+++ b/Help/prop_dir/COMPILE_DEFINITIONS.rst
@@ -3,18 +3,30 @@ COMPILE_DEFINITIONS
 
 Preprocessor definitions for compiling a directory's sources.
 
-The COMPILE_DEFINITIONS property may be set to a semicolon-separated
-list of preprocessor definitions using the syntax VAR or VAR=value.
+This property specifies the list of options given so far to the
+:command:`add_definitions` command.
+
+The ``COMPILE_DEFINITIONS`` property may be set to a semicolon-separated
+list of preprocessor definitions using the syntax ``VAR`` or ``VAR=value``.
 Function-style definitions are not supported.  CMake will
 automatically escape the value correctly for the native build system
 (note that CMake language syntax may require escapes to specify some
-values).  This property may be set on a per-configuration basis using
-the name COMPILE_DEFINITIONS_<CONFIG> where <CONFIG> is an upper-case
-name (ex.  "COMPILE_DEFINITIONS_DEBUG").  This property will be
-initialized in each directory by its value in the directory's parent.
+values).
+
+This property will be initialized in each directory by its value in the
+directory's parent.
 
 CMake will automatically drop some definitions that are not supported
 by the native build tool.  The VS6 IDE does not support definition
 values with spaces (but NMake does).
 
 .. include:: /include/COMPILE_DEFINITIONS_DISCLAIMER.txt
+
+Contents of ``COMPILE_DEFINITIONS`` may use "generator expressions" with
+the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
+manual for more on defining buildsystem properties.
+
+The corresponding :prop_dir:`COMPILE_DEFINITIONS_<CONFIG>` property may
+be set to specify per-configuration definitions.  Generator expressions
+should be preferred instead of setting the alternative property.
diff --git a/Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst b/Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst
index 0876ddf7c8..c22606b90f 100644
--- a/Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst
+++ b/Help/prop_dir/COMPILE_DEFINITIONS_CONFIG.rst
@@ -3,6 +3,15 @@ COMPILE_DEFINITIONS_<CONFIG>
 
 Per-configuration preprocessor definitions in a directory.
 
-This is the configuration-specific version of COMPILE_DEFINITIONS.
+This is the configuration-specific version of :prop_dir:`COMPILE_DEFINITIONS`
+where ``<CONFIG>`` is an upper-case name (ex. ``COMPILE_DEFINITIONS_DEBUG``).
+
 This property will be initialized in each directory by its value in
 the directory's parent.
+
+Contents of ``COMPILE_DEFINITIONS_<CONFIG>`` may use "generator expressions"
+with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
+manual for more on defining buildsystem properties.
+
+Generator expressions should be preferred instead of setting this property.
diff --git a/Help/prop_dir/COMPILE_OPTIONS.rst b/Help/prop_dir/COMPILE_OPTIONS.rst
index f0c3a42387..59530597dc 100644
--- a/Help/prop_dir/COMPILE_OPTIONS.rst
+++ b/Help/prop_dir/COMPILE_OPTIONS.rst
@@ -3,12 +3,14 @@ COMPILE_OPTIONS
 
 List of options to pass to the compiler.
 
-This property specifies the list of directories given so far for this
-property.  This property exists on directories and targets.
+This property specifies the list of options given so far to the
+:command:`add_compile_options` command.
 
-The target property values are used by the generators to set the
-options for the compiler.
+This property is used to populate the :prop_tgt:`COMPILE_OPTIONS` target
+property, which is used by the generators to set the options for the
+compiler.
 
-Contents of COMPILE_OPTIONS may use "generator expressions" with the syntax
-``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual for
-available expressions.
+Contents of ``COMPILE_OPTIONS`` may use "generator expressions" with the
+syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)` manual
+for available expressions.  See the :manual:`cmake-buildsystem(7)` manual
+for more on defining buildsystem properties.
diff --git a/Help/prop_dir/INCLUDE_DIRECTORIES.rst b/Help/prop_dir/INCLUDE_DIRECTORIES.rst
index 6c5782f538..baba49bf35 100644
--- a/Help/prop_dir/INCLUDE_DIRECTORIES.rst
+++ b/Help/prop_dir/INCLUDE_DIRECTORIES.rst
@@ -4,15 +4,23 @@ INCLUDE_DIRECTORIES
 List of preprocessor include file search directories.
 
 This property specifies the list of directories given so far to the
-include_directories command.  This property exists on directories and
-targets.  In addition to accepting values from the include_directories
-command, values may be set directly on any directory or any target
-using the set_property command.  A target gets its initial value for
-this property from the value of the directory property.  A directory
-gets its initial value from its parent directory if it has one.  Both
-directory and target property values are adjusted by calls to the
-include_directories command.
+:command:`include_directories` command.
+
+This property is used to populate the :prop_tgt:`INCLUDE_DIRECTORIES`
+target property, which is used by the generators to set the include
+directories for the compiler.
+
+In addition to accepting values from that command, values may be set
+directly on any directory using the :command:`set_property` command.  A
+directory gets its initial value from its parent directory if it has one.
+The intial value of the :prop_tgt:`INCLUDE_DIRECTORIES` target property
+comes from the value of this property.  Both directory and target property
+values are adjusted by calls to the :command:`include_directories` command.
 
 The target property values are used by the generators to set the
-include paths for the compiler.  See also the include_directories
-command.
+include paths for the compiler.
+
+Contents of ``INCLUDE_DIRECTORIES`` may use "generator expressions" with
+the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
+manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
+manual for more on defining buildsystem properties.