Help: Improve readability and fix inaccuracies in unity build docs

1 files changed, 18 insertions, 8 deletions

diff --git a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst
index 84047f2..44ffe27 100644
--- a/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst
+++ b/Help/prop_tgt/UNITY_BUILD_BATCH_SIZE.rst
@@ -1,13 +1,23 @@
 UNITY_BUILD_BATCH_SIZE
 ----------------------
 
-Specifies how many source code files will be included into a
-:prop_tgt:`UNITY_BUILD` source file.
+Specifies the maximum number of source files that can be combined into any one
+unity source file when unity builds are enabled by the :prop_tgt:`UNITY_BUILD`
+target property.  The original source files will be distributed across as many
+unity source files as necessary to honor this limit.
 
-If the property is not set, CMake will use the value provided
-by :variable:`CMAKE_UNITY_BUILD_BATCH_SIZE`.
+The initial value for this property is taken from the
+:variable:`CMAKE_UNITY_BUILD_BATCH_SIZE` variable when the target is created.
+If that variable has not been set, the initial value will be 8.
 
-By setting it to value `0` the generated unity source file will
-contain all the source files that would otherwise be split
-into multiple batches. It is not recommended to do so, since it
-would affect performance.
+The batch size needs to be selected carefully.  If set too high, the size of
+the combined source files could result in the compiler using excessive memory
+or hitting other similar limits.  In extreme cases, this can even result in
+build failure.  On the other hand, if the batch size is too low, there will be
+little gain in build performance.
+
+Although strongly discouraged, the batch size may be set to a value of 0 to
+combine all the sources for the target into a single unity file, regardless of
+how many sources are involved.  This runs the risk of creating an excessively
+large unity source file and negatively impacting the build performance, so
+a value of 0 is not generally recommended.