Help: Specify COMPILE_OPTIONS and COMPILE_FLAGS source properties usage

Help/prop_sf/COMPILE_FLAGS.rst

@@ -3,9 +3,9 @@ COMPILE_FLAGS
 
 Additional flags to be added when compiling this source file.
 
-The ``COMPILE_FLAGS`` property sets additional compiler flags used to build
-source files.  Use :prop_sf:`COMPILE_DEFINITIONS` to pass additional
-preprocessor definitions.
+The ``COMPILE_FLAGS`` property, managed as a string, sets additional compiler
+flags used to build source files.  Use :prop_sf:`COMPILE_DEFINITIONS` to pass
+additional preprocessor definitions.
 
 Contents of ``COMPILE_FLAGS`` may use "generator expressions"
 with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
@@ -13,3 +13,7 @@ manual for available expressions.  However, :generator:`Xcode`
 does not support per-config per-source settings, so expressions
 that depend on the build configuration are not allowed with that
 generator.
+
+.. note::
+
+  This property has been superseded by the :prop_sf:`COMPILE_OPTIONS` property.

Help/prop_sf/COMPILE_OPTIONS.rst

@@ -15,3 +15,7 @@ for available expressions.  However, :generator:`Xcode`
 does not support per-config per-source settings, so expressions
 that depend on the build configuration are not allowed with that
 generator.
+
+.. note::
+
+  This property should be preferred over the :prop_sf:`COMPILE_FLAGS` property.