diff --git a/lib/keyboard.js b/lib/keyboard.js
index 2ba21aa..3bbc15f 100755
--- a/lib/keyboard.js
+++ b/lib/keyboard.js
@@ -127,18 +127,21 @@ var KEYBOARD_HANDLER_PROPAGATE = true
  * 		...
  * }
  *
- * <key-def> can be:
- * 	- explicit key code
- * 	- key name, if present in _SPECIAL_KEYS)
- * 	- key char (uppercase), as is returned by String.fromCharCode(...) 
  *
+ * <key-def> can be:
+ * 	- explicit key code, e.g. 65
+ * 	- key name, if present in _SPECIAL_KEYS, e.g. Enter
+ * 	- key char (uppercase), as is returned by String.fromCharCode(...) e.g. A
+ *
+ *
+ * NOTE: to rest what to use as <key-def> use toKeyCode(..) / toKeyName(..).
  * NOTE: all fields are optional.
  * NOTE: if a handler explicitly returns false then that will break the 
  * 		event propagation chain and exit the handler.
  * 		i.e. no other matching handlers will be called.
  * NOTE: a <css-selector> is used as a predicate to select a section to 
  * 		use. if multiple selectors match something then multiple sections 
- * 		will be resolved in order of occurance.
+ * 		will be resolved in order of occurrence.
  *
  * XXX might need to add meta information to generate sensible help...
  */