Add some comments to summoning-bell-cmd-ring procedure

diff --git a/worlds/bricabrac.scm b/worlds/bricabrac.scm
index e0688d014ce18018613c29a71322e3131ba01ecb..372515ede66d206292df8445bd660df71dd6c70d 100644 (file)
--- a/worlds/bricabrac.scm
+++ b/worlds/bricabrac.scm
@@ -200,18 +200,34 @@ character.\n")))
    (simple-dispatcher summoning-bell-actions*)))
 
 (define-mhandler (summoning-bell-cmd-ring bell message)
+  ;; Call back to actor who invoked this message handler
+  ;; and find out their name.  We'll call *their* get-name message
+  ;; handler... meanwhile, this procedure suspends until we get
+  ;; their response.
   (define who-rang
     (message-ref
      (<-wait bell (message-from message) 'get-name)
      'val))
+  ;; Now we'll invoke the "tell" message handler on the player
+  ;; who rang us, displaying this text on their screen.
+  ;; This one just uses <- instead of <-wait, since we don't
+  ;; care when it's delivered; we're not following up on it.
   (<- bell (message-from message) 'tell
       #:text "*ring ring!*  You ring the bell!\n")
+  ;; We also want everyone else in the room to "hear" the bell,
+  ;; but they get a different message since they aren't the ones
+  ;; ringing it.  Notice here's where we make use of the invoker's
+  ;; name as extracted and assigned to the who-rang variable.
+  ;; Notice how we send this message to our "location", which
+  ;; forwards it to the rest of the occupants in the room.
   (<- bell (gameobj-loc bell) 'tell-room
       #:text
       (format #f "*ring ring!*  ~a rings the bell!\n"
               who-rang)
       #:exclude (message-from message))
-
+  ;; Now we perform the primary task of the bell, which is to summon
+  ;; the "clerk" character to the room.  (This is configurable,
+  ;; so we dynamically look up their address.)
   (<- bell (dyn-ref bell (slot-ref bell 'summons)) 'be-summoned
       #:who-summoned (message-from message)))