Improve docs for 'eval-when'.

* doc/ref/api-macros.texi (Eval When): Explain in detail what each
  condition means, including 'expand' which was previously undocumented.
  Change the example to use (expand load eval) and recommend that set of
  conditions, instead of (compile load eval) which was previously
  recommended and shown in the example.

1 files changed, 30 insertions, 5 deletions

diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi
index acfbc6556..c2910a44e 100644
--- a/doc/ref/api-macros.texi
+++ b/doc/ref/api-macros.texi
@@ -1186,17 +1186,42 @@ The fix is to use @code{eval-when}.
 @example
 ;; correct: using eval-when
 (use-modules (srfi srfi-19))
-(eval-when (compile load eval)
+(eval-when (expand load eval)
   (define (date) (date->string (current-date))))
 (define-syntax %date (identifier-syntax (date)))
 (define *compilation-date* %date)
 @end example
 
 @deffn {Syntax} eval-when conditions exp...
-Evaluate @var{exp...} under the given @var{conditions}. Valid conditions include
-@code{eval}, @code{load}, and @code{compile}. If you need to use
-@code{eval-when}, use it with all three conditions, as in the above example.
-Other uses of @code{eval-when} may void your warranty or poison your cat.
+Evaluate @var{exp...} under the given @var{conditions}.  Valid
+conditions include:
+
+@table @code
+@item expand
+Evaluate during macro expansion, whether compiling or not.
+
+@item load
+Evaluate during the evaluation phase of compiled code, e.g. when loading
+a compiled module or running compiled code at the REPL.
+
+@item eval
+Evaluate during the evaluation phase of non-compiled code.
+
+@item compile
+Evaluate during macro expansion, but only when compiling.
+@end table
+
+In other words, when using the primitive evaluator, @code{eval-when}
+expressions with @code{expand} are run during macro expansion, and those
+with @code{eval} are run during the evaluation phase.
+
+When using the compiler, @code{eval-when} expressions with either
+@code{expand} or @code{compile} are run during macro expansion, and
+those with @code{load} are run during the evaluation phase.
+
+When in doubt, use the three conditions @code{(expand load eval)}, as in
+the example above.  Other uses of @code{eval-when} may void your
+warranty or poison your cat.
 @end deffn
 
 @node Internal Macros