From da531374022d9e8aedf6911bc18127e0db8da7db Mon Sep 17 00:00:00 2001
From: Tim Schaub <tim.schaub@gmail.com>
Date: Wed, 11 Jul 2007 17:51:12 +0000
Subject: [PATCH] documenting keyMask, checkModifiers, and the Handler
 constants associated with them

git-svn-id: http://svn.openlayers.org/trunk/openlayers@3702 dc9f47b5-9b13-0410-9fdd-eb0c1a62fdaf
---
 lib/OpenLayers/Handler.js | 44 ++++++++++++++++++++++++++++++++++++---
 1 file changed, 41 insertions(+), 3 deletions(-)

diff --git a/lib/OpenLayers/Handler.js b/lib/OpenLayers/Handler.js
index 4c81310ea3..7fd6523785 100644
--- a/lib/OpenLayers/Handler.js
+++ b/lib/OpenLayers/Handler.js
@@ -28,9 +28,28 @@
  */
 OpenLayers.Handler = OpenLayers.Class.create();
 
+/**
+ * Constant: OpenLayers.Handler.MOD_NONE
+ * If set as the <keyMask>, <checkModifiers> returns false if any key is down.
+ */
 OpenLayers.Handler.MOD_NONE  = 0;
+
+/**
+ * Constant: OpenLayers.Handler.MOD_SHIFT
+ * If set as the <keyMask>, <checkModifiers> returns false if Shift is down.
+ */
 OpenLayers.Handler.MOD_SHIFT = 1;
+
+/**
+ * Constant: OpenLayers.Handler.MOD_CTRL
+ * If set as the <keyMask>, <checkModifiers> returns false if Ctrl is down.
+ */
 OpenLayers.Handler.MOD_CTRL  = 2;
+
+/**
+ * Constant: OpenLayers.Handler.MOD_ALT
+ * If set as the <keyMask>, <checkModifiers> returns false if Alt is down.
+ */
 OpenLayers.Handler.MOD_ALT   = 4;
 
 OpenLayers.Handler.prototype = {
@@ -55,8 +74,21 @@ OpenLayers.Handler.prototype = {
     map: null,
 
     /**
-     * Property: keyMask
-     * {Integer}
+     * APIProperty: keyMask
+     * {Integer} Use bitwise operators and one or more of the OpenLayers.Handler
+     *     constants to construct a keyMask.  The keyMask is used by
+     *     <checkModifiers>.  If the keyMask matches the combination of keys
+     *     down on an event, checkModifiers returns true.
+     *
+     * Example:
+     * (code)
+     *     // handler only responds if the Shift key is down
+     *     handler.keyMask = OpenLayers.Handler.MOD_SHIFT;
+     *
+     *     // handler only responds if Ctrl-Shift is down
+     *     handler.keyMask = OpenLayers.Handler.MOD_SHIFT |
+     *                       OpenLayers.Handler.MOD_CTRL;
+     * (end)
      */
     keyMask: null,
 
@@ -102,7 +134,13 @@ OpenLayers.Handler.prototype = {
     },
 
     /**
-     * Method: checkModifiers 
+     * Method: checkModifiers
+     * Check the keyMask on the handler.  If no <keyMask> is set, this always
+     *     returns true.  If a <keyMask> is set and it matches the combination
+     *     of keys down on an event, this returns true.
+     *
+     * Returns:
+     * {Boolean} The keyMask matches the keys down on an event.
      */
     checkModifiers: function (evt) {
         if(this.keyMask == null) {