[example ] mostly adding some docstrings to eg 10

1 files changed, 20 insertions, 5 deletions

diff --git a/examples/10-canvas-sneks.lisp b/examples/10-canvas-sneks.lisp
index 453ef0e..a69b429 100644
--- a/examples/10-canvas-sneks.lisp
+++ b/examples/10-canvas-sneks.lisp
@@ -37,6 +37,11 @@
       (setf (dy snek) (random-between -1 1))))
 
 (defun advance-snek-pos (snek)
+  "Advance a snek's position. Check that the snek remains contained in
+its HOME. If it isn't, revert position and have the snek change its
+mind about where it wants to go. Finally, update the snek's BOD,
+ensuring that its BOD is no longer than LEN, truncating it when
+necessary."
   (with-slots (x y dx dy home bod len) snek
     (incf x dx)
     (incf y dy)
@@ -46,10 +51,12 @@
       (snek-change-mind snek))
     (push y bod)
     (push x bod)
-    (when (< len (length bod)) 
+    (when (<= (* 2 len) (length bod)) 
       (setf bod (nreverse (cddr (nreverse bod)))))))
 
 (defun snek-thots (snek)
+  "A SNEK will decide to change direction the longer it has been
+moving in a particular direction."
   (incf (brain snek) 0.01)
   (when (< (random 1.0) (brain snek))
     (setf (brain snek) 0.0)
@@ -59,15 +66,20 @@
   (advance-snek-pos snek)
   (snek-thots snek))
 
+(defvar *alpha-step* 10)
+
 (defun draw-snek (snek canvas)
+  "Draws a snek to a canvas.  The BOD of a snek is a list of recent
+positions that the snek's head had occupied. The body is drawn by
+reducing the alpha of the snek's COLOR by 10 for every point in the BOD."
   (with-slots (bod color) snek
     (destructuring-bind (red green blue) color 
-      (let ((alpha 255))
+      (let ((alpha (max 0 (- 255 (* *alpha-step* (/ (length bod) 2))))))
         (loop
-          for (x y . more) on bod by #'cddr
+          for (y x . more) on (reverse bod) by #'cddr
           do (ww::with-pixel (r g b a) (ww::pixel canvas x y)
                (setf r red g green b blue a alpha))
-             (setf alpha (max 0 (- alpha  10))))))))
+             (setf alpha (min 255 (+ alpha  *alpha-step*))))))))
 
 (defun random-snek (&optional (boundx 100) (boundy 100))
   (make-instance 'snek
@@ -81,6 +93,8 @@
 
 (ww:defhandler sneks-a-go-go
     (ww::on-perframe (app ticks)
+      "Clears cavnas. Moves gives each snek its turn. Draws each
+       snek. Updates the screen."
       (with-slots (sneks snek-pit) app
         (ww::clear-canvas snek-pit)
         (dolist (snek sneks)
@@ -89,7 +103,8 @@
         (ww::blit snek-pit))))
 
 (defmethod ww::boot ((app sneking ))
-  "Adds the intro text and sets up the start button handler."
+  "Sets up snek-pit, a canvas to which sneks are drawn. Creates random
+sneks. Adds the canvas to the app, and sets up the perframe handler."
   (setf (snek-pit app)
         (make-instance 'ww:canvas :pixel-width 100 :pixel-height 100)
         (sneks app)