Clarify when the commands block is executed during rez-build

wiki/pages/Building-Packages.md

@@ -76,10 +76,10 @@ build environment, but the details of the build itself are left open for the use
 Having said that, *cmake* has been supported by rez for some time, and rez comes with a
 decent amount of utility code to manage cmake builds.
 
-When a rez environment is configured, each package's [commands](Package-Definition-Guide#commands)
-section configures the environment. When a build is occurring, a special variable
-[building](Package-Commands#building) is set to *True*. Your packages should use this
-variable to communicate build information to the package being built.
+When a rez environment is configured, each required package's
+[commands](Package-Definition-Guide#commands) section configures the environment for the building
+package to use. When a build is occurring, a special variable [building](Package-Commands#building) is set to *True*. Your required packages should use this variable to communicate build information
+to the package being built.
 
 For example, our *boost* package's commands might look like so:
 
@@ -88,6 +88,11 @@ For example, our *boost* package's commands might look like so:
             # there is a 'FindBoost.cmake' file in this dir..
             env.CMAKE_MODULE_PATH.append("{root}/cmake")
 
+When *boost* is required into another package's build environment, `building` will be set to
+*True*, thereby executing that block of code, but otherwise, it will not be executed, even when
+*boost* itself is building (because the `commands` block is not executed by a package during its
+own building).
+
 A (very simple) *FindBoost.cmake* file might look like this:
 
     set(Boost_INCLUDE_DIRS $ENV{REZ_BOOST_ROOT}/include)

wiki/pages/Package-Commands.md

@@ -290,8 +290,10 @@ Do not check this variable to detect if an installation is occurring - see `buil
         env.FOO_INCLUDE_PATH = "{root}/include"
 
 This boolean variable is *True* if a build is occurring (typically done via the *rez-build* tool),
-and *False* otherwise. Typically a package will use this variable to set environment variables that
-are only useful during a build - C++ header include paths are a good example.
+and *False* otherwise, however, the `commands` block is only executed when the package is brought
+into a resolved environment, so this is not used when the package itself is building. Typically a
+package will use this variable to set environment variables that are only useful during when other
+packages are being built - C++ header include paths are a good example.
 
 ### command
 *Function*

wiki/pages/Package-Definition-Guide.md

@@ -546,9 +546,10 @@ enabled. If not provided, this is determined from the global config setting [def
         env.PYTHONPATH.append("{root}/python")
         env.PATH.append("{root}/bin")
 
-This is a block of python code which tells rez how to update an environment so that this package can
-be used. There is a python API provided (see [here](Package-Commands) for more details) that lets
-you do things such as:
+This is a block of python code which tells rez how to update an environment so that this package
+can be used. It is executed when the package is brought into a rez environment, either by explicit
+request or by another package's requirements. There is a python API provided (see
+[here](Package-Commands) for more details) that lets you do things such as:
 
 * set, unset, prepend and append environment variables;
 * create aliases;