[docs] added docstrings to exports

1 files changed, 120 insertions, 27 deletions

diff --git a/src/events/event-handler.lisp b/src/events/event-handler.lisp
index c8b83d0..a7f1b1b 100644
--- a/src/events/event-handler.lisp
+++ b/src/events/event-handler.lisp
@@ -27,7 +27,16 @@ can be redefined using this form to support interactive development."
 
 (defmacro on-perframe
     ((&optional (target 'target) (time 'time)) &body body)
-  "Creates a handler for 'PERFRAME events"
+  "Creates a handler for 'PERFRAME events.
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
+ TARGET - the object currently handling the event 
+ TIME - The current time in milliseconds
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::perframe
@@ -40,12 +49,19 @@ can be redefined using this form to support interactive development."
 (defmacro on-keydown
     ((&optional (target 'target) (scancode 'scancode) (modifiers 'modifiers)) &body body)
   "Creates a lambda suitable for the value of a keydown event
-  handler. The function accepts two positional arguments TARGET and
-  SCANCODE and one &REST argument MODIFIERS.
+  handler. 
 
-  SCANCODE will be a keyword of the form :SCANCODE-A, :SCANCODE-B ...
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
 
-  The members of MODIFIERS look like :LSHIFT, :RCTRL, RALT, etc"
+ The function accepts two positional arguments TARGET and SCANCODE and
+ one &REST argument MODIFIERS.
+
+ SCANCODE will be a keyword of the form :SCANCODE-A, :SCANCODE-B ...
+
+ The members of MODIFIERS look like :LSHIFT, :RCTRL, RALT, etc"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::keydown
@@ -60,7 +76,15 @@ can be redefined using this form to support interactive development."
 (defmacro on-keyup
     ((&optional (target 'target) (scancode 'scancode) (modifiers 'modifiers)) &body body)
   "Creates a lambda suitable for the value of a keyup event
-  handler. The function accepts two positional arguments TARGET and
+  handler. 
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
+
+  The function accepts two positional arguments TARGET and
   SCANCODE and one &REST argument MODIFIERS.
 
   SCANCODE will be a keyword of the form :SCANCODE-A, :SCANCODE-B ...
@@ -86,18 +110,19 @@ can be redefined using this form to support interactive development."
         (win-x 'win-x) (win-y 'win-y)
         (win-xrel 'win-xrel) (win-yrel 'win-yrel))
      &body body)
-    "ON-MOUSEMOTION defines a mouse motion event handler.  All
-variable arguments supplied the the ON-MOUSEDOWN handler form are
-optional. You may supply your own variables to use in your BODY or you
-may just refer to the defaults - they will be interned in the
-appropriate package.
-
-- TARGET is the object ontowhich the handler was installed
-- X and Y are the scaled screen coordinates 
-- XREL and YREL are the relative motion of the X and Y positions since
-  the last event, in scaled coordinates
-- STATE is the button state, see the SDL2 docs
-- WIN-* variables are the unscaled event values, if you require them.
+    "ON-MOUSEMOTION defines a mouse motion event handler.  
+
+ All variable arguments supplied to this handler form are optional. You
+ may supply your own variables to use in your BODY or you may just
+ refer to the defaults - they will be interned in the appropriate
+ package.
+
+ - TARGET is the object ontowhich the handler was installed
+ - X and Y are the scaled screen coordinates 
+ - XREL and YREL are the relative motion of the X and Y positions since
+   the last event, in scaled coordinates
+ - STATE is the button state, see the SDL2 docs
+ - WIN-* variables are the unscaled event values, if you require them.
 "
 
   `(make-instance
@@ -131,7 +156,19 @@ appropriate package.
         (clicks 'clicks) (button 'button)
         (win-x 'win-x) (win-y 'win-y))
      &body body)
-  "Creates a handler for MOUSEDOWN events"
+  "Creates a handler for MOUSEDOWN events.
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
+ - TARGET is the object ontowhich the handler was installed
+ - X and Y are the scaled screen coordinates 
+ - BUTTON is a code for the mouse button pressed (see sdl docs)
+ - CLICKS is the number of clicks 1 for single, 2 for double.
+ - WIN-* variables are the unscaled event values, if you require them.
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::mousedown
@@ -159,7 +196,20 @@ appropriate package.
         (clicks 'clicks) (button 'button)
         (win-x 'win-x) (win-y 'win-y))
      &body body)
-  "Creates a handler for MOUSEUP events"
+  "Creates a handler for MOUSEUP events
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
+ - TARGET is the object ontowhich the handler was installed
+ - X and Y are the scaled screen coordinates 
+ - BUTTON is a code for the mouse button pressed (see sdl docs)
+ - CLICKS is the number of clicks 1 for single, 2 for double.
+ - WIN-* variables are the unscaled event values, if you require them.
+
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::mouseup
@@ -183,7 +233,18 @@ appropriate package.
 
 (defmacro on-mousewheel
     ((&optional (target 'target) (horiz 'horiz) (vert 'vert) (dir 'dir)) &body body)
-  "Creates a handler for MOUSEWHEEL events"
+  "Creates a handler for MOUSEWHEEL events
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
+ - TARGET is the object ontowhich the handler was installed
+ - HORIZ, VERT are 1 or -1
+ - DIR is normal or flipped, see https://wiki.libsdl.org/SDL_MouseWheelEvent
+
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::mousewheel
@@ -202,7 +263,14 @@ appropriate package.
 (defmacro on-blur
     ((&optional (target 'target)) &body body)
   "Creates a handler for BLUR events. BLUR is a psuedo event that
-fires whenever an object loses focus."
+fires whenever an object loses focus.
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::blur
@@ -216,6 +284,12 @@ fires whenever an object loses focus."
     ((&optional (target 'target)) &body body)
   "Creates a handler for a FOCUS event. FOCUS is a pusedo event that
 fires when the FOCUS slot of the current APPLICATION instance is changed.
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
 "
   `(make-instance
     'event-handler
@@ -229,7 +303,14 @@ fires when the FOCUS slot of the current APPLICATION instance is changed.
 (defmacro on-before-dropped
     ((&optional (target 'target)) &body body)
   "Creates a handler for BEFORE-DROPPED events, which fire before a
-  unit is removed from its container."
+  unit is removed from its container.
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::before-dropped
@@ -240,9 +321,15 @@ fires when the FOCUS slot of the current APPLICATION instance is changed.
                         ,@body)))
 
 (defmacro on-before-added
-    ((&optional (container 'container) (target 'target)) &body body)
+    ((&optional  (target 'target) (container 'container)) &body body)
   "Creates a handler for BEFORE-ADDED events, which fire before a unit
-  is added to a container."
+  TARGET is added to CONTAINER.
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::before-added
@@ -257,9 +344,15 @@ fires when the FOCUS slot of the current APPLICATION instance is changed.
 
 
 (defmacro on-after-added
-    ((&optional (container 'container) (target 'target)) &body body)
+    ((&optional  (target 'target) (container 'container)) &body body)
   "Creates a handler for AFTER-ADDED events, which fire after a unit
-  is added to a container."
+  is added to a container.
+
+ All variable arguments supplied to this handler form are
+ optional. You may supply your own variables to use in your BODY or
+ you may just refer to the defaults - they will be interned in the
+ appropriate package.
+"
   `(make-instance
     'event-handler
     :event-type 'wheelwork::after-added