more docs on hostattrs in unevaluated propspecs and in DEFPROPSPEC

Signed-off-by: Sean Whitton <spwhitton@spwhitton.name>

2 files changed, 20 insertions, 4 deletions

diff --git a/doc/propspecs.rst b/doc/propspecs.rst
index d2454a1..b3d4d39 100644
--- a/doc/propspecs.rst
+++ b/doc/propspecs.rst
@@ -137,6 +137,19 @@ property combinators.
 
 The ``PROPS`` macro converts an unevaluated propspec into a propspec.
 
+The evaluation of arguments to propapps in unevaluated propspecs appearing in
+calls to ``DEFHOST``, ``DEPLOYS.`` and ``DEPLOYS-THESE.`` cannot retrieve
+hostattrs, because these propspecs will be evaluated as part of the initial
+definitions of hosts, before they have any hostattrs.  By contrast, the
+unevaluated propspecs in calls to ``DEFPROPLIST``, ``DEPLOY``, and
+``DEPLOY-THESE``, and the code which produces propspecs in ``DEFPROPSPEC``,
+may retrieve hostattrs set by other properties, because that code is run in
+the context of a host which has already been defined.  You cannot retrieve
+hostattrs set by properties in the propspec resulting from evaluating the
+evaluated propspec, however, since that propspec has not yet been applied to
+the host.  New hostattrs should not be pushed outside of the definitions of
+``:HOSTATTRS`` subroutines.
+
 The elements of unevaluated propspecs are typically arguments to macros, such
 that the context of evaluation for forms which produce the arguments to the
 propapps is the context in which the call to the containing macro appears.
diff --git a/src/property.lisp b/src/property.lisp
index e3bdcde..a3c6382 100644
--- a/src/property.lisp
+++ b/src/property.lisp
@@ -273,7 +273,9 @@ any such string is a list beginning with :DESC, the remainder will be used as
 the :DESC subroutine for the resulting property, like DEFPROP.  Otherwise, the
 body defines a function of the arguments specified by the lambda list which
 returns the propspec to be evaluated and applied.  It should be a pure
-function aside from retrieving hostattrs.
+function aside from retrieving hostattrs (as set by other properties applied
+to the hosts to which the resulting property is applied, not as set by the
+properties in the returned propspec).
 
 You can usually use DEFPROPLIST instead of DEFPROPSPEC, which see."
   ;; This is implemented by effectively pushing a null pointer to the front of
@@ -315,9 +317,10 @@ those in LAMBDA.  LAMBDA is an ordinary lambda list, so you can use &AUX
 variables to compute intermediate values.  The evaluation of arguments to
 propapps in PROPERTIES, and the evaluation of any &AUX variables in LAMBDA,
 will happen at :HOSTATTRS-time for the host to which the resulting property is
-to be applied, so you can retrieve static informational attributes (unlike
-with unevaluated property application specifications appearing in DEFHOST
-forms).  The evaluation should otherwise be purely functional.
+to be applied, so you can retrieve static informational attributes set by
+other properties applied to the host (unlike with unevaluated property
+application specifications appearing in DEFHOST forms).  The evaluation should
+otherwise be purely functional.
 
 You will usually be able to use DEFPROPLIST instead of DEFPROPSPEC.  However,
 sometimes you will need to fall back on DEFPROPSPEC.  For example, an