Improve clarify of early binding functions documentation (#1677)

Improve clarify of early binding functions documentation by documenting what is accessible within an early function.


Signed-off-by: Bryce Gattis <[email protected]>

Author: BryceGattis

docs/source/building_packages.rst

@@ -23,6 +23,8 @@ package with two python-based variants might look like this:
 
 The current working directory is set to the *build path* during a build.
 
+.. _the-build-environment:
+
 The Build Environment
 =====================
 

docs/source/environment.rst

@@ -121,8 +121,8 @@ removed**:
 Build Environment Variables
 ===========================
 
-These are variables that rez generates within a build environment, in addition
-to those listed :ref:`here <context-environment-variables>`.
+These are variables that rez generates within a :ref:`build environment <the-build-environment>`, in addition
+to context environment variables listed :ref:`here <context-environment-variables>`.
 
 .. glossary::
 

docs/source/package_definition.rst

@@ -79,11 +79,19 @@ and *late binding* functions - and these are decorated using ``@early`` and ``@l
 Early Binding Functions
 +++++++++++++++++++++++
 
-Early binding functions use the ``@early`` decorator. They are evaluated at *build time*, hence the
-'early' in 'early binding'. Any package attribute can be implemented as an early binding function.
-
-Here is an example of an :attr:`authors` attribute that is automatically set to the contributors of the
-package's git project:
+Early binding functions use the ``@early`` decorator. They are evaluated at
+*build time*, hence the 'early' in 'early binding' and their definition persists
+in the installed ``package.py``. By 'build time', it is meant that they are
+evaluated before the resolve has occurred, and as such, before the
+:ref:`build environment <the-build-environment>` has been constructed. Therefore
+there are some important distinctions that set early-bound functions apart from
+other function attributes:
+
+- The :attr:`this` object only exposes package attributes. Nothing else is accessible when inside an early-bound function.
+- No rez-set :doc:`environment variables <environment>` can be accessed inside an early bound function.
+
+Any package attribute can be implemented as an early binding function. Here is an example of an :attr:`authors`
+attribute that is automatically set to the contributors of the package's git project:
 
 .. code-block:: python