X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/blobdiff_plain/dea4d05507e59ab779ed4bb209e05971d87e260c..bf090e021a5c20da452a4841cdfb8eb78e29544e:/src/proto-module.lisp

diff --git a/src/proto-module.lisp b/src/proto-module.lisp
index aa167e4..93034a4 100644
--- a/src/proto-module.lisp
+++ b/src/proto-module.lisp
@@ -102,9 +102,10 @@ (export '*module*)
 (defparameter *module* nil
   "The current module under construction.
 
-   This is always an instance of MODULE.  Once we've finished constructing
-   it, we'll call `change-class' to turn it into an instance of whatever type
-   is requested in the module's `:lisp-class' property.")
+   During module construction, this is always an instance of `module'.  Once
+   we've finished constructing it, we'll call `change-class' to turn it into
+   an instance of whatever type is requested in the module's `:lisp-class'
+   property.")
 
 (export 'module-import)
 (defgeneric module-import (object)
@@ -137,10 +138,10 @@ (defgeneric finalize-module (module)
    particular, it will change the class (using `change-class') of the module
    according to the class choice set in the module's `:lisp-class' property.
    This has the side effects of calling `shared-initialize', setting the
-   module's state to T, and checking for unrecognized properties.  (Therefore
-   subclasses should add a method to `shared-initialize' taking care of
-   looking at interesting properties, just to make sure they're ticked
-   off.)"))
+   module's state to `t', and checking for unrecognized
+   properties.  (Therefore subclasses should add a method to
+   `shared-initialize' taking care of looking at interesting properties, just
+   to make sure they're ticked off.)"))
 
 ;;;--------------------------------------------------------------------------
 ;;; Module objects.
@@ -180,19 +181,27 @@ (export 'define-module)
 (defmacro define-module
     ((name &key (truename nil truenamep) (location nil locationp))
      &body body)
-  "Define a new module.
+  "Define and return a new module.
 
-   The module will be called NAME; it will be included in the *module-map*
+   The module will be called NAME; it will be included in the `*module-map*'
    only if it has a TRUENAME (which defaults to the truename of NAME, or nil
    if there is no file with that name).  The module is populated by
-   evaluating the BODY in a dynamic environment where *module* is bound to
+   evaluating the BODY in a dynamic environment where `*module*' is bound to
    the module under construction, and any other module variables are bound to
    appropriate initial values -- see `*module-bindings-alist*' and
    `define-module-var'.
 
+   If a module with the same NAME is already known, then it is returned
+   unchanged: the BODY is not evaluated.
+
+   The LOCATION may be any printable value other than `t' (though
+   `file-location' objects are most usual) indicating what provoked this
+   module definition: it gets reported to the user if an import cycle is
+   detected.  This check is made only if a TRUENAME is supplied.
+
    Evaluation order irregularity: the TRUENAME and LOCATION arguments are
    always evaluated in that order, regardless of their order in the macro
-   call site."
+   call site (which this macro can't detect)."
 
   `(build-module ,name
 		 (lambda () ,@body)