Code review fixes:

* Use .hasClass() instead of .is() where possible
* More succinct math operators in DropdownEventHandler._tryToSelect()
* Document language-change events
* Improve some more JS code hints docs

Author: peterflynn

src/document/Document.js

@@ -65,6 +65,9 @@ define(function (require, exports, module) {
      *
      * __deleted__ -- When the file for this document has been deleted. All views onto the document should
      * be closed. The document will no longer be editable or dispatch "change" events.
+     * 
+     * __languageChanged__ -- When the value of getLanguage() has changed. 2nd argument is the old value,
+     * 3rd argument is the new value.
      *
      * @constructor
      * @param {!File} file  Need not lie within the project.

src/extensions/default/JavaScriptCodeHints/ScopeManager.js

@@ -1137,7 +1137,7 @@ define(function (require, exports, module) {
          * Called each time a new editor becomes active.
          *
          * @param {Session} session - the active hinting session
-         * @param {Document} document - the document of the editor that has changed
+         * @param {!Document} document - the document of the editor that has changed
          * @param {?Document} previousDocument - the document of the editor is changing from
          */
         function handleEditorChange(session, document, previousDocument) {

src/extensions/default/JavaScriptCodeHints/main.js

@@ -563,7 +563,7 @@ define(function (require, exports, module) {
          * When the editor is changed, reset the hinting session and cached 
          * information, and reject any pending deferred requests.
          * 
-         * @param {Editor} editor - editor context to be initialized.
+         * @param {!Editor} editor - editor context to be initialized.
          * @param {?Editor} previousEditor - the previous editor.
          */
         function initializeSession(editor, previousEditor) {
@@ -575,10 +575,10 @@ define(function (require, exports, module) {
         }
 
         /*
-         * Install editor change listeners
+         * Connects to the given editor, creating a new Session & adding listeners
          * 
-         * @param {Editor} editor - editor context on which to listen for
-         *      changes
+         * @param {?Editor} editor - editor context on which to listen for
+         *      changes. If null, 'session' is cleared.
          * @param {?Editor} previousEditor - the previous editor
          */
         function installEditorListeners(editor, previousEditor) {

src/language/LanguageManager.js

@@ -120,6 +120,12 @@
  *         isBinary: true    
  *     }); 
  * 
+ * 
+ * LanguageManager dispatches two events:
+ * 
+ *  - languageAdded -- When any new Language is added. 2nd arg is the new Language.
+ *  - languageModified -- When the attributes of a Language change, or when the Language gains or loses
+ *          file extension / filename mappings. 2nd arg is the modified Language.
  */
 define(function (require, exports, module) {
     "use strict";

src/utils/DropdownEventHandler.js

@@ -171,7 +171,7 @@ define(function (require, exports, module) {
      * @param {boolean=} noWrap  Clip out of range index values instead of wrapping. Default false (wrap).
      */
     DropdownEventHandler.prototype._tryToSelect = function (index, direction, noWrap) {
-        // Wrap around if index out of bounds (>= len or < 0)
+        // Fix up 'index' if out of bounds (>= len or < 0)
         var len = this.$items.length;
         if (noWrap) {
             // Clip to stay in range (and set direction so we don't wrap in the recursion case either)
@@ -183,9 +183,10 @@ define(function (require, exports, module) {
                 direction = -1;
             }
         } else {
-            index = index % len;
+            // Wrap around to keep index in bounds
+            index %= len;
             if (index < 0) {
-                index = len + index;
+                index += len;
             }
         }
 
@@ -240,7 +241,7 @@ define(function (require, exports, module) {
         if (!this.selectionCallback || !this.$list || !$link) {
             return;
         }
-        if ($link.is(".disabled")) {
+        if ($link.hasClass("disabled")) {
             return;
         }
 
@@ -296,7 +297,7 @@ define(function (require, exports, module) {
 
                 // Only set selected if enabled & in view
                 // (dividers are already screened out since they don't have an "a" tag in them)
-                if (!$link.is(".disabled")) {
+                if (!$link.hasClass("disabled")) {
                     if (elementOffset.top < viewOffset.top + self.$list.height() && viewOffset.top <= elementOffset.top) {
                         self._setSelectedIndex(self.$items.index($item), false);
                     }