From: Christopher Allan Webber <cwebber@dustycloud.org>
Date: Sun, 11 Dec 2016 00:01:30 +0000 (-0600)
Subject: Add some comments to summoning-bell-cmd-ring procedure
X-Git-Tag: fosdem-2017~134
X-Git-Url: https://jxself.org/git/?p=mudsync.git;a=commitdiff_plain;h=009fc4606e1a141fd182a38718b9954ecfdd62a5;hp=242f214ff5d4e3c0df4687799819c104e7fb1a78

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

diff --git a/worlds/bricabrac.scm b/worlds/bricabrac.scm
index e0688d0..372515e 100644
--- 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)))