Merge pull request #305 from glyptodon/fix-jsdoc

GUAC-791: Fix JSDoc comments and upgrade to JSDoc 3.

guacamole-common-js/jsdoc-conf.json

@@ -0,0 +1,9 @@
+{
+    "source" : {
+        "include" : "src"
+    },
+    "opts" : {
+        "recurse" : true,
+        "destination" : "target/site/jsdoc"
+    }
+}

guacamole-common-js/src/main/webapp/modules/AudioPlayer.js

@@ -129,7 +129,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * The format of audio this player will decode.
      *
      * @private
-     * @type Guacamole.RawAudioPlayer._Format
+     * @type {Guacamole.RawAudioPlayer._Format}
      */
     var format = Guacamole.RawAudioPlayer._Format.parse(mimetype);
 
@@ -138,7 +138,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * Web Audio API is not supported.
      *
      * @private
-     * @type AudioContext
+     * @type {AudioContext}
      */
     var context = (function getAudioContext() {
 
@@ -167,7 +167,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * resolution.
      *
      * @private
-     * @type Number
+     * @type {Number}
      */
     var nextPacketTime = context.currentTime;
 
@@ -176,7 +176,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * provided with this Guacamole.RawAudioPlayer was created.
      *
      * @private
-     * @type Guacamole.ArrayBufferReader
+     * @type {Guacamole.ArrayBufferReader}
      */
     var reader = new Guacamole.ArrayBufferReader(stream);
 
@@ -188,7 +188,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      *
      * @private
      * @constant
-     * @type Number
+     * @type {Number}
      */
     var MIN_SPLIT_SIZE = 0.02;
 
@@ -198,7 +198,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * roughly one third of a second.
      *
      * @private
-     * @type Number
+     * @type {Number}
      */
     var maxLatency = 0.3;
 
@@ -218,7 +218,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * sample, and will be 128 for 8-bit audio and 32768 for 16-bit audio.
      *
      * @private
-     * @type Number
+     * @type {Number}
      */
     var maxSampleValue = (format.bytesPerSample === 1) ? 128 : 32768;
 
@@ -230,7 +230,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * no further modifications can be made to that packet.
      *
      * @private
-     * @type SampleArray[]
+     * @type {SampleArray[]}
      */
     var packetQueue = [];
 
@@ -361,6 +361,7 @@ Guacamole.RawAudioPlayer = function RawAudioPlayer(stream, mimetype) {
      * dynamically according to the click-reduction algorithm implemented by
      * splitAudioPacket().
      *
+     * @private
      * @returns {SampleArray}
      *     A packet of audio data pulled from the beginning of the playback
      *     queue.
@@ -493,21 +494,21 @@ Guacamole.RawAudioPlayer._Format = function _Format(template) {
      * The number of bytes in each sample of audio data. This value is
      * independent of the number of channels.
      *
-     * @type Number
+     * @type {Number}
      */
     this.bytesPerSample = template.bytesPerSample;
 
     /**
      * The number of audio channels (ie: 1 for mono, 2 for stereo).
      *
-     * @type Number
+     * @type {Number}
      */
     this.channels = template.channels;
 
     /**
      * The number of samples per second, per channel.
      *
-     * @type Number
+     * @type {Number}
      */
     this.rate = template.rate;
 

guacamole-common-js/src/main/webapp/modules/Client.js

@@ -69,11 +69,17 @@ Guacamole.Client = function(tunnel) {
 
     /**
      * The underlying Guacamole display.
+     *
+     * @private
+     * @type {Guacamole.Display}
      */
     var display = new Guacamole.Display();
 
     /**
      * All available layers and buffers
+     *
+     * @private
+     * @type {Object.<Number, (Guacamole.Display.VisibleLayer|Guacamole.Layer)>}
      */
     var layers = {};
     
@@ -81,7 +87,8 @@ Guacamole.Client = function(tunnel) {
      * All audio players currently in use by the client. Initially, this will
      * be empty, but audio players may be allocated by the server upon request.
      *
-     * @type Object.<Number, Guacamole.AudioPlayer>
+     * @private
+     * @type {Object.<Number, Guacamole.AudioPlayer>}
      */
     var audioPlayers = {};
 
@@ -89,7 +96,8 @@ Guacamole.Client = function(tunnel) {
      * All video players currently in use by the client. Initially, this will
      * be empty, but video players may be allocated by the server upon request.
      *
-     * @type Object.<Number, Guacamole.VideoPlayer>
+     * @private
+     * @type {Object.<Number, Guacamole.VideoPlayer>}
      */
     var videoPlayers = {};
 
@@ -103,7 +111,8 @@ Guacamole.Client = function(tunnel) {
      * All current objects. The index of each object is dictated by the
      * Guacamole server.
      *
-     * @type Guacamole.Object[]
+     * @private
+     * @type {Guacamole.Object[]}
      */
     var objects = [];
 
@@ -554,11 +563,15 @@ Guacamole.Client = function(tunnel) {
      * Returns the layer with the given index, creating it if necessary.
      * Positive indices refer to visible layers, an index of zero refers to
      * the default layer, and negative indices refer to buffers.
-     * 
+     *
-     * @param {Number} index The index of the layer to retrieve.
+     * @private
-     * @return {Guacamole.Display.VisibleLayer|Guacamole.Layer} The layer having the given index.
+     * @param {Number} index
+     *     The index of the layer to retrieve.
+     *
+     * @return {Guacamole.Display.VisibleLayer|Guacamole.Layer}
+     *     The layer having the given index.
      */
-    function getLayer(index) {
+    var getLayer = function getLayer(index) {
 
         // Get layer, create if necessary
         var layer = layers[index];
@@ -579,7 +592,7 @@ Guacamole.Client = function(tunnel) {
 
         return layer;
 
-    }
+    };
 
     function getParser(index) {
 

guacamole-common-js/src/main/webapp/modules/DataURIReader.js

@@ -43,7 +43,8 @@ Guacamole.DataURIReader = function(stream, mimetype) {
     /**
      * Current data URI.
      *
-     * @type String
+     * @private
+     * @type {String}
      */
     var uri = 'data:' + mimetype + ';base64,';
 

guacamole-common-js/src/main/webapp/modules/Display.js

@@ -82,7 +82,7 @@ Guacamole.Display = function() {
      * the relative location within the image of the mouse cursor at which
      * each click occurs.
      * 
-     * @type Number
+     * @type {Number}
      */
     this.cursorHotspotX = 0;
 
@@ -91,7 +91,7 @@ Guacamole.Display = function() {
      * the relative location within the image of the mouse cursor at which
      * each click occurs.
      * 
-     * @type Number
+     * @type {Number}
      */
     this.cursorHotspotY = 0;
 
@@ -101,7 +101,7 @@ Guacamole.Display = function() {
      * the location of the cursor image within the Guacamole display, as
      * last set by moveCursor().
      * 
-     * @type Number
+     * @type {Number}
      */
     this.cursorX = 0;
 
@@ -111,7 +111,7 @@ Guacamole.Display = function() {
      * the location of the cursor image within the Guacamole display, as
      * last set by moveCursor().
      * 
-     * @type Number
+     * @type {Number}
      */
     this.cursorY = 0;
 
@@ -143,7 +143,7 @@ Guacamole.Display = function() {
      * front of the queue (FIFO). These tasks will eventually be grouped
      * into a Frame.
      * @private
-     * @type Task[]
+     * @type {Task[]}
      */
     var tasks = [];
 
@@ -151,7 +151,7 @@ Guacamole.Display = function() {
      * The queue of all frames. Each frame is a pairing of an array of tasks
      * and a callback which must be called when the frame is rendered.
      * @private
-     * @type Frame[]
+     * @type {Frame[]}
      */
     var frames = [];
 
@@ -251,7 +251,7 @@ Guacamole.Display = function() {
         /**
          * Whether this Task is blocked.
          * 
-         * @type boolean
+         * @type {boolean}
          */
         this.blocked = blocked;
 
@@ -1141,7 +1141,7 @@ Guacamole.Display.VisibleLayer = function(width, height) {
      * to the Guacamole protocol, and not relevant at this level.
      * 
      * @private
-     * @type Number
+     * @type {Number}
      */
     this.__unique_id = Guacamole.Display.VisibleLayer.__next_id++;
 
@@ -1154,20 +1154,20 @@ Guacamole.Display.VisibleLayer = function(width, height) {
     /**
      * X coordinate of the upper-left corner of this layer container within
      * its parent, in pixels.
-     * @type Number
+     * @type {Number}
      */
     this.x = 0;
 
     /**
      * Y coordinate of the upper-left corner of this layer container within
      * its parent, in pixels.
-     * @type Number
+     * @type {Number}
      */
     this.y = 0;
 
     /**
      * Z stacking order of this layer relative to other sibling layers.
-     * @type Number
+     * @type {Number}
      */
     this.z = 0;
 
@@ -1177,13 +1177,13 @@ Guacamole.Display.VisibleLayer = function(width, height) {
      * three values being the first row, and the last three values being the
      * second row. There are six values total.
      * 
-     * @type Number[]
+     * @type {Number[]}
      */
     this.matrix = [1, 0, 0, 1, 0, 0];
 
     /**
      * The parent layer container of this layer, if any.
-     * @type Guacamole.Display.VisibleLayer
+     * @type {Guacamole.Display.VisibleLayer}
      */
     this.parent = null;
 
@@ -1382,6 +1382,6 @@ Guacamole.Display.VisibleLayer = function(width, height) {
  * the layer, which exists at the protocol/client level only.
  * 
  * @private
- * @type Number
+ * @type {Number}
  */
 Guacamole.Display.VisibleLayer.__next_id = 0;

guacamole-common-js/src/main/webapp/modules/InputStream.js

@@ -40,7 +40,7 @@ Guacamole.InputStream = function(client, index) {
 
     /**
      * The index of this stream.
-     * @type Number
+     * @type {Number}
      */
     this.index = index;
 

guacamole-common-js/src/main/webapp/modules/IntegerPool.js

@@ -31,18 +31,22 @@ Guacamole.IntegerPool = function() {
 
     /**
      * Reference to this integer pool.
+     *
+     * @private
      */
     var guac_pool = this;
 
     /**
      * Array of available integers.
-     * @type Number[]
+     *
+     * @private
+     * @type {Number[]}
      */
     var pool = [];
 
     /**
      * The next integer to return if no more integers remain.
-     * @type Number
+     * @type {Number}
      */
     this.next_int = 0;
 

guacamole-common-js/src/main/webapp/modules/JSONReader.js

@@ -38,7 +38,7 @@ Guacamole.JSONReader = function guacamoleJSONReader(stream) {
      * Reference to this Guacamole.JSONReader.
      *
      * @private
-     * @type Guacamole.JSONReader
+     * @type {Guacamole.JSONReader}
      */
     var guacReader = this;
 
@@ -46,7 +46,7 @@ Guacamole.JSONReader = function guacamoleJSONReader(stream) {
      * Wrapped Guacamole.StringReader.
      *
      * @private
-     * @type Guacamole.StringReader
+     * @type {Guacamole.StringReader}
      */
     var stringReader = new Guacamole.StringReader(stream);
 
@@ -54,7 +54,7 @@ Guacamole.JSONReader = function guacamoleJSONReader(stream) {
      * All JSON read thus far.
      *
      * @private
-     * @type String
+     * @type {String}
      */
     var json = '';
 

guacamole-common-js/src/main/webapp/modules/Keyboard.js

@@ -77,14 +77,14 @@ Guacamole.Keyboard = function(element) {
          * An arbitrary timestamp in milliseconds, indicating this event's
          * position in time relative to other events.
          *
-         * @type Number
+         * @type {Number}
          */
         this.timestamp = new Date().getTime();
 
         /**
          * Whether the default action of this key event should be prevented.
          *
-         * @type Boolean
+         * @type {Boolean}
          */
         this.defaultPrevented = false;
 
@@ -93,7 +93,7 @@ Guacamole.Keyboard = function(element) {
          * by a best-effort guess using available event properties and keyboard
          * state.
          *
-         * @type Number
+         * @type {Number}
          */
         this.keysym = null;
 
@@ -102,7 +102,7 @@ Guacamole.Keyboard = function(element) {
          * If false, the keysym may still be valid, but it's only a best guess,
          * and future key events may be a better source of information.
          *
-         * @type Boolean
+         * @type {Boolean}
          */
         this.reliable = false;
 
@@ -145,7 +145,7 @@ Guacamole.Keyboard = function(element) {
         /**
          * The JavaScript key code of the key pressed.
          *
-         * @type Number
+         * @type {Number}
          */
         this.keyCode = keyCode;
 
@@ -153,7 +153,7 @@ Guacamole.Keyboard = function(element) {
          * The legacy DOM3 "keyIdentifier" of the key pressed, as defined at:
          * http://www.w3.org/TR/2009/WD-DOM-Level-3-Events-20090908/#events-Events-KeyboardEvent
          *
-         * @type String
+         * @type {String}
          */
         this.keyIdentifier = keyIdentifier;
 
@@ -161,7 +161,7 @@ Guacamole.Keyboard = function(element) {
          * The standard name of the key pressed, as defined at:
          * http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
          * 
-         * @type String
+         * @type {String}
          */
         this.key = key;
 
@@ -170,7 +170,7 @@ Guacamole.Keyboard = function(element) {
          * defined at:
          * http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
          * 
-         * @type Number
+         * @type {Number}
          */
         this.location = location;
 
@@ -228,7 +228,7 @@ Guacamole.Keyboard = function(element) {
          * The Unicode codepoint of the character that would be typed by the
          * key pressed.
          *
-         * @type Number
+         * @type {Number}
          */
         this.charCode = charCode;
 
@@ -268,7 +268,7 @@ Guacamole.Keyboard = function(element) {
         /**
          * The JavaScript key code of the key released.
          *
-         * @type Number
+         * @type {Number}
          */
         this.keyCode = keyCode;
 
@@ -276,7 +276,7 @@ Guacamole.Keyboard = function(element) {
          * The legacy DOM3 "keyIdentifier" of the key released, as defined at:
          * http://www.w3.org/TR/2009/WD-DOM-Level-3-Events-20090908/#events-Events-KeyboardEvent
          *
-         * @type String
+         * @type {String}
          */
         this.keyIdentifier = keyIdentifier;
 
@@ -284,7 +284,7 @@ Guacamole.Keyboard = function(element) {
          * The standard name of the key released, as defined at:
          * http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
          * 
-         * @type String
+         * @type {String}
          */
         this.key = key;
 
@@ -293,7 +293,7 @@ Guacamole.Keyboard = function(element) {
          * defined at:
          * http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
          * 
-         * @type Number
+         * @type {Number}
          */
         this.location = location;
 
@@ -313,7 +313,8 @@ Guacamole.Keyboard = function(element) {
      * An array of recorded events, which can be instances of the private
      * KeydownEvent, KeypressEvent, and KeyupEvent classes.
      *
-     * @type (KeydownEvent|KeypressEvent|KeyupEvent)[]
+     * @private
+     * @type {KeyEvent[]}
      */
     var eventLog = [];
 
@@ -541,6 +542,8 @@ Guacamole.Keyboard = function(element) {
      * by keysym. This is used to prevent/allow default actions for key events,
      * even when the onkeydown handler cannot be called again because the key
      * is (theoretically) still pressed.
+     *
+     * @private
      */
     var last_keydown_result = {};
 
@@ -549,7 +552,7 @@ Guacamole.Keyboard = function(element) {
      * fired. This object maps keycodes to keysyms.
      *
      * @private
-     * @type Object.<Number, Number>
+     * @type {Object.<Number, Number>}
      */
     var recentKeysym = {};
 
@@ -571,19 +574,22 @@ Guacamole.Keyboard = function(element) {
      * for the given location, or the keysym for the standard location if
      * undefined.
      * 
-     * @param {Array} keysyms An array of keysyms, where the index of the
+     * @private
-     *                        keysym in the array is the location value.
+     * @param {Number[]} keysyms
-     * @param {Number} location The location on the keyboard corresponding to
+     *     An array of keysyms, where the index of the keysym in the array is
-     *                          the key pressed, as defined at:
+     *     the location value.
-     *                          http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
+     *
+     * @param {Number} location
+     *     The location on the keyboard corresponding to the key pressed, as
+     *     defined at: http://www.w3.org/TR/DOM-Level-3-Events/#events-KeyboardEvent
      */
-    function get_keysym(keysyms, location) {
+    var get_keysym = function get_keysym(keysyms, location) {
 
         if (!keysyms)
             return null;
 
         return keysyms[location] || keysyms[0];
-    }
+    };
 
     function keysym_from_key_identifier(identifier, location, shifted) {
 
@@ -651,15 +657,18 @@ Guacamole.Keyboard = function(element) {
      * the keyCode is the Unicode codepoint for that key. This is not
      * correct in all cases.
      *
-     * @param {Number} keyCode The keyCode from a browser keydown/keyup
+     * @private
-     *                         event.
+     * @param {Number} keyCode
-     * @param {String} keyIdentifier The legacy keyIdentifier from a
+     *     The keyCode from a browser keydown/keyup event.
-     *                               browser keydown/keyup event.
+     *
-     * @returns {Boolean} true if the keyIdentifier looks sane, false if
+     * @param {String} keyIdentifier
-     *                    the keyIdentifier appears incorrectly derived or
+     *     The legacy keyIdentifier from a browser keydown/keyup event.
-     *                    is missing entirely.
+     *
+     * @returns {Boolean}
+     *     true if the keyIdentifier looks sane, false if the keyIdentifier
+     *     appears incorrectly derived or is missing entirely.
      */
-    function key_identifier_sane(keyCode, keyIdentifier) {
+    var key_identifier_sane = function key_identifier_sane(keyCode, keyIdentifier) {
 
         // Missing identifier is not sane
         if (!keyIdentifier)
@@ -684,7 +693,7 @@ Guacamole.Keyboard = function(element) {
         // The keyIdentifier does NOT appear sane
         return false;
 
-    }
+    };
 
     /**
      * Marks a key as pressed, firing the keydown event if registered. Key
@@ -777,10 +786,12 @@ Guacamole.Keyboard = function(element) {
      * Given a keyboard event, updates the local modifier state and remote
      * key state based on the modifier flags within the event. This function
      * pays no attention to keycodes.
-     * 
+     *
-     * @param {KeyboardEvent} e The keyboard event containing the flags to update.
+     * @private
+     * @param {KeyboardEvent} e
+     *     The keyboard event containing the flags to update.
      */
-    function update_modifier_state(e) {
+    var update_modifier_state = function update_modifier_state(e) {
 
         // Get state
         var state = Guacamole.Keyboard.ModifierState.fromKeyboardEvent(e);
@@ -819,13 +830,14 @@ Guacamole.Keyboard = function(element) {
         // Update state
         guac_keyboard.modifiers = state;
 
-    }
+    };
 
     /**
      * Reads through the event log, removing events from the head of the log
      * when the corresponding true key presses are known (or as known as they
      * can be).
      * 
+     * @private
      * @return {Boolean} Whether the default action of the latest event should
      *                   be prevented.
      */
@@ -850,10 +862,11 @@ Guacamole.Keyboard = function(element) {
     /**
      * Releases Ctrl+Alt, if both are currently pressed and the given keysym
      * looks like a key that may require AltGr.
-     * 
+     *
+     * @private
      * @param {Number} keysym The key that was just pressed.
      */
-    function release_simulated_altgr(keysym) {
+    var release_simulated_altgr = function release_simulated_altgr(keysym) {
 
         // Both Ctrl+Alt must be pressed if simulated AltGr is in use
         if (!guac_keyboard.modifiers.ctrl || !guac_keyboard.modifiers.alt)
@@ -875,7 +888,7 @@ Guacamole.Keyboard = function(element) {
             guac_keyboard.release(0xFFEA); // Right alt
         }
 
-    }
+    };
 
     /**
      * Reads through the event log, interpreting the first event, if possible,
@@ -883,10 +896,12 @@ Guacamole.Keyboard = function(element) {
      * total lack of events or the need for more events, null is returned. Any
      * interpreted events are automatically removed from the log.
      * 
-     * @return {KeyEvent} The first key event in the log, if it can be
+     * @private
-     *                    interpreted, or null otherwise.
+     * @return {KeyEvent}
+     *     The first key event in the log, if it can be interpreted, or null
+     *     otherwise.
      */
-    function interpret_event() {
+    var interpret_event = function interpret_event() {
 
         // Peek at first event in log
         var first = eventLog[0];
@@ -973,13 +988,14 @@ Guacamole.Keyboard = function(element) {
         // No event interpreted
         return null;
 
-    }
+    };
 
     /**
      * Returns the keyboard location of the key associated with the given
      * keyboard event. The location differentiates key events which otherwise
      * have the same keycode, such as left shift vs. right shift.
      *
+     * @private
      * @param {KeyboardEvent} e
      *     A JavaScript keyboard event, as received through the DOM via a
      *     "keydown", "keyup", or "keypress" handler.
@@ -1086,31 +1102,31 @@ Guacamole.Keyboard.ModifierState = function() {
     
     /**
      * Whether shift is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.shift = false;
     
     /**
      * Whether ctrl is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.ctrl = false;
     
     /**
      * Whether alt is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.alt = false;
     
     /**
      * Whether meta (apple key) is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.meta = false;
 
     /**
      * Whether hyper (windows key) is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.hyper = false;
     

guacamole-common-js/src/main/webapp/modules/Layer.js

@@ -210,20 +210,20 @@ Guacamole.Layer = function(width, height) {
      *     layer.autosize = true;
      * });
      * 
-     * @type Boolean
+     * @type {Boolean}
      * @default false
      */
     this.autosize = false;
 
     /**
      * The current width of this layer.
-     * @type Number
+     * @type {Number}
      */
     this.width = width;
 
     /**
      * The current height of this layer.
-     * @type Number
+     * @type {Number}
      */
     this.height = height;
 

guacamole-common-js/src/main/webapp/modules/Mouse.js

@@ -66,7 +66,7 @@ Guacamole.Mouse = function(element) {
      * mouse events fire. This state object is also passed in as a parameter to
      * the handler of any mouse events.
      * 
-     * @type Guacamole.Mouse.State
+     * @type {Guacamole.Mouse.State}
      */
     this.currentState = new Guacamole.Mouse.State(
         0, 0, 
@@ -119,6 +119,8 @@ Guacamole.Mouse = function(element) {
      * Cumulative scroll delta amount. This value is accumulated through scroll
      * events and results in scroll button clicks if it exceeds a certain
      * threshold.
+     *
+     * @private
      */
     var scroll_delta = 0;
 
@@ -336,7 +338,7 @@ Guacamole.Mouse = function(element) {
      * coordinates.
      *
      * @private
-     * @type Boolean
+     * @type {Boolean}
      */
     var CSS3_CURSOR_SUPPORTED = (function() {
 
@@ -419,31 +421,31 @@ Guacamole.Mouse.State = function(x, y, left, middle, right, up, down) {
 
     /**
      * The current X position of the mouse pointer.
-     * @type Number
+     * @type {Number}
      */
     this.x = x;
 
     /**
      * The current Y position of the mouse pointer.
-     * @type Number
+     * @type {Number}
      */
     this.y = y;
 
     /**
      * Whether the left mouse button is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.left = left;
 
     /**
      * Whether the middle mouse button is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.middle = middle;
 
     /**
      * Whether the right mouse button is currently pressed.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.right = right;
 
@@ -451,7 +453,7 @@ Guacamole.Mouse.State = function(x, y, left, middle, right, up, down) {
      * Whether the up mouse button is currently pressed. This is the fourth
      * mouse button, associated with upward scrolling of the mouse scroll
      * wheel.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.up = up;
 
@@ -459,7 +461,7 @@ Guacamole.Mouse.State = function(x, y, left, middle, right, up, down) {
      * Whether the down mouse button is currently pressed. This is the fifth 
      * mouse button, associated with downward scrolling of the mouse scroll
      * wheel.
-     * @type Boolean
+     * @type {Boolean}
      */
     this.down = down;
 
@@ -542,7 +544,7 @@ Guacamole.Mouse.Touchpad = function(element) {
      * mouse events fire. This state object is also passed in as a parameter to
      * the handler of any mouse events.
      * 
-     * @type Guacamole.Mouse.State
+     * @type {Guacamole.Mouse.State}
      */
     this.currentState = new Guacamole.Mouse.State(
         0, 0, 
@@ -789,6 +791,8 @@ Guacamole.Mouse.Touchscreen = function(element) {
     /**
      * Whether a gesture is known to be in progress. If false, touch events
      * will be ignored.
+     *
+     * @private
      */
     var gesture_in_progress = false;
 
@@ -806,11 +810,15 @@ Guacamole.Mouse.Touchscreen = function(element) {
 
     /**
      * The timeout associated with the delayed, cancellable click release.
+     *
+     * @private
      */
     var click_release_timeout = null;
 
     /**
      * The timeout associated with long-press for right click.
+     *
+     * @private
      */
     var long_press_timeout = null;
 
@@ -843,7 +851,7 @@ Guacamole.Mouse.Touchscreen = function(element) {
      * mouse events fire. This state object is also passed in as a parameter to
      * the handler of any mouse events.
      *
-     * @type Guacamole.Mouse.State
+     * @type {Guacamole.Mouse.State}
      */
     this.currentState = new Guacamole.Mouse.State(
         0, 0,

guacamole-common-js/src/main/webapp/modules/Namespace.js

@@ -0,0 +1,29 @@
+/*
+ * Copyright (C) 2015 Glyptodon LLC
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+
+/**
+ * The namespace used by the Guacamole JavaScript API. Absolutely all classes
+ * defined by the Guacamole JavaScript API will be within this namespace.
+ *
+ * @namespace
+ */
+var Guacamole = Guacamole || {};

guacamole-common-js/src/main/webapp/modules/Object.js

@@ -39,18 +39,16 @@ Guacamole.Object = function guacamoleObject(client, index) {
      * Reference to this Guacamole.Object.
      *
      * @private
-     * @type Guacamole.Object
+     * @type {Guacamole.Object}
      */
     var guacObject = this;
 
     /**
-     * The callbacks associated with all pending input stream requests, if the
+     * Map of stream name to corresponding queue of callbacks. The queue of
-     * default onbody handling is in use.
+     * callbacks is guaranteed to be in order of request.
      *
      * @private
-     * @type Object.<String, Function[]>
+     * @type {Object.<String, Function[]>}
-     *     Map of stream name to corresponding queue of callbacks. The queue of
-     *     callbacks is guaranteed to be in order of request.
      */
     var bodyCallbacks = {};
 
@@ -112,7 +110,7 @@ Guacamole.Object = function guacamoleObject(client, index) {
     /**
      * The index of this object.
      *
-     * @type Number
+     * @type {Number}
      */
     this.index = index;
 
@@ -200,7 +198,7 @@ Guacamole.Object = function guacamoleObject(client, index) {
  * the root stream MUST be a JSON map of stream name to mimetype.
  *
  * @constant
- * @type String
+ * @type {String}
  */
 Guacamole.Object.ROOT_STREAM = '/';
 
@@ -210,6 +208,6 @@ Guacamole.Object.ROOT_STREAM = '/';
  * have this mimetype.
  *
  * @constant
- * @type String
+ * @type {String}
  */
 Guacamole.Object.STREAM_INDEX_MIMETYPE = 'application/vnd.glyptodon.guacamole.stream-index+json';

guacamole-common-js/src/main/webapp/modules/OnScreenKeyboard.js

@@ -36,7 +36,8 @@ Guacamole.OnScreenKeyboard = function(layout) {
     /**
      * Reference to this Guacamole.OnScreenKeyboard.
      *
-     * @type Guacamole.OnScreenKeyboard
+     * @private
+     * @type {Guacamole.OnScreenKeyboard}
      */
     var osk = this;
 
@@ -46,7 +47,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * released.
      *
      * @private
-     * @type Object.<String, Number>
+     * @type {Object.<String, Number>}
      */
     var modifierKeysyms = {};
 
@@ -55,7 +56,8 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * pressed, it may not be in this map at all, but all pressed keys will
      * have a corresponding mapping to true.
      *
-     * @type Object.<String, Boolean>
+     * @private
+     * @type {Object.<String, Boolean>}
      */
     var pressed = {};
 
@@ -66,7 +68,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * experience rounding error due to unit conversions.
      *
      * @private
-     * @type ScaledElement[]
+     * @type {ScaledElement[]}
      */
     var scaledElements = [];
 
@@ -133,7 +135,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * while non-zero, mouse events will have no effect.
      *
      * @private
-     * @type Number
+     * @type {Number}
      */
     var ignoreMouse = 0;
 
@@ -175,7 +177,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
          * The width of this ScaledElement, in arbitrary units, relative to
          * other ScaledElements.
          *
-         * @type Number
+         * @type {Number}
          */
          this.width = width;
 
@@ -183,7 +185,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
          * The height of this ScaledElement, in arbitrary units, relative to
          * other ScaledElements.
          *
-         * @type Number
+         * @type {Number}
          */
          this.height = height;
  
@@ -214,6 +216,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * Returns whether all modifiers having the given names are currently
      * active.
      *
+     * @private
      * @param {String[]} names
      *     The names of all modifiers to test.
      *
@@ -242,6 +245,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * given name, where that Key object's requirements (such as pressed
      * modifiers) are all currently satisfied.
      *
+     * @private
      * @param {String} keyName
      *     The name of the key to retrieve.
      *
@@ -279,6 +283,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * element with the "guac-keyboard-pressed" CSS class. If the key is
      * already pressed, this function has no effect.
      *
+     * @private
      * @param {String} keyName
      *     The name of the key to press.
      *
@@ -346,6 +351,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * "guac-keyboard-pressed" CSS class from the associated element. If the
      * key is already released, this function has no effect.
      *
+     * @private
      * @param {String} keyName
      *     The name of the key to release.
      *
@@ -396,7 +402,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * The number of mousemove events to require before re-enabling mouse
      * event handling after receiving a touch event.
      *
-     * @type Number
+     * @type {Number}
      */
     this.touchMouseThreshold = 3;
 
@@ -419,7 +425,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
     /**
      * The keyboard layout provided at time of construction.
      *
-     * @type Guacamole.OnScreenKeyboard.Layout
+     * @type {Guacamole.OnScreenKeyboard.Layout}
      */
     this.layout = new Guacamole.OnScreenKeyboard.Layout(layout);
 
@@ -535,7 +541,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
      * Map of all key names to their corresponding set of keys. Each key name
      * may correspond to multiple keys due to the effect of modifiers.
      *
-     * @type Object.<String, Guacamole.OnScreenKeyboard.Key[]>
+     * @type {Object.<String, Guacamole.OnScreenKeyboard.Key[]>}
      */
     this.keys = getKeys(layout.keys);
 
@@ -705,6 +711,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
              * key. Touch events will result in mouse events being ignored for
              * touchMouseThreshold events.
              *
+             * @private
              * @param {TouchEvent} e
              *     The touch event being handled.
              */
@@ -719,6 +726,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
              * key. Touch events will result in mouse events being ignored for
              * touchMouseThreshold events.
              *
+             * @private
              * @param {TouchEvent} e
              *     The touch event being handled.
              */
@@ -733,6 +741,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
              * key. If mouse events are currently being ignored, this handler
              * does nothing.
              *
+             * @private
              * @param {MouseEvent} e
              *     The touch event being handled.
              */
@@ -747,6 +756,7 @@ Guacamole.OnScreenKeyboard = function(layout) {
              * key. If mouse events are currently being ignored, this handler
              * does nothing.
              *
+             * @private
              * @param {MouseEvent} e
              *     The touch event being handled.
              */
@@ -793,7 +803,7 @@ Guacamole.OnScreenKeyboard.Layout = function(template) {
      * informational purposes only, but it is recommend to conform to the
      * [language code]_[country code] format.
      *
-     * @type String
+     * @type {String}
      */
     this.language = template.language;
 
@@ -801,7 +811,7 @@ Guacamole.OnScreenKeyboard.Layout = function(template) {
      * The type of keyboard layout, such as "qwerty". This property is for
      * informational purposes only, and does not conform to any standard.
      *
-     * @type String
+     * @type {String}
      */
     this.type = template.type;
 
@@ -811,7 +821,7 @@ Guacamole.OnScreenKeyboard.Layout = function(template) {
      * implicitly. In all cases, the name property of the key object will be
      * taken from the name given in the mapping.
      *
-     * @type Object.<String, Number|String|Guacamole.OnScreenKeyboard.Key|Guacamole.OnScreenKeyboard.Key[]>
+     * @type {Object.<String, Number|String|Guacamole.OnScreenKeyboard.Key|Guacamole.OnScreenKeyboard.Key[]>}
      */
     this.keys = template.keys;
 
@@ -824,7 +834,7 @@ Guacamole.OnScreenKeyboard.Layout = function(template) {
      * numbers present will be transformed into gaps of that size, scaled
      * according to the same units as each key.
      *
-     * @type Object
+     * @type {Object}
      */
     this.layout = template.layout;
 
@@ -834,7 +844,7 @@ Guacamole.OnScreenKeyboard.Layout = function(template) {
      * the same units. The conversion factor between these units and pixels is
      * derived later via a call to resize() on the Guacamole.OnScreenKeyboard.
      *
-     * @type Number
+     * @type {Number}
      */
     this.width = template.width;
 
@@ -844,7 +854,7 @@ Guacamole.OnScreenKeyboard.Layout = function(template) {
      * overall size of the keyboard. If not defined here, the width of each
      * key will default to 1.
      *
-     * @type Object.<String, Number>
+     * @type {Object.<String, Number>}
      */
     this.keyWidths = template.keyWidths || {};
 
@@ -872,7 +882,7 @@ Guacamole.OnScreenKeyboard.Key = function(template, name) {
     /**
      * The unique name identifying this key within the keyboard layout.
      *
-     * @type String
+     * @type {String}
      */
     this.name = name || template.name;
 
@@ -880,7 +890,7 @@ Guacamole.OnScreenKeyboard.Key = function(template, name) {
      * The human-readable title that will be displayed to the user within the
      * key. If not provided, this will be derived from the key name.
      *
-     * @type String
+     * @type {String}
      */
     this.title = template.title || this.name;
 
@@ -889,7 +899,7 @@ Guacamole.OnScreenKeyboard.Key = function(template, name) {
      * not provided, this will be derived from the title if the title is a
      * single character.
      *
-     * @type Number
+     * @type {Number}
      */
     this.keysym = template.keysym || (function deriveKeysym(title) {
 
@@ -918,7 +928,7 @@ Guacamole.OnScreenKeyboard.Key = function(template, name) {
      * the "shift" modifier, for example. By default, the key will affect no
      * modifiers.
      * 
-     * @type String
+     * @type {String}
      */
     this.modifier = template.modifier;
 
@@ -929,7 +939,7 @@ Guacamole.OnScreenKeyboard.Key = function(template, name) {
      * is named "shift" within the layout. By default, the key will require
      * no modifiers.
      *
-     * @type String[]
+     * @type {String[]}
      */
     this.requires = template.requires || [];
 

guacamole-common-js/src/main/webapp/modules/OutputStream.js

@@ -39,7 +39,7 @@ Guacamole.OutputStream = function(client, index) {
 
     /**
      * The index of this stream.
-     * @type Number
+     * @type {Number}
      */
     this.index = index;
 

guacamole-common-js/src/main/webapp/modules/Status.js

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2014 Glyptodon LLC
+ * Copyright (C) 2015 Glyptodon LLC
  *
  * Permission is hereby granted, free of charge, to any person obtaining a copy
  * of this software and associated documentation files (the "Software"), to deal
@@ -26,10 +26,13 @@ var Guacamole = Guacamole || {};
  * A Guacamole status. Each Guacamole status consists of a status code, defined
  * by the protocol, and an optional human-readable message, usually only
  * included for debugging convenience.
- * 
+ *
- * @param {Number} code The Guacamole status code, as defined by
+ * @constructor
- *                      Guacamole.Status.Code.
+ * @param {Number} code
- * @param {String} [message] An optional human-readable message.
+ *     The Guacamole status code, as defined by Guacamole.Status.Code.
+ *
+ * @param {String} [message]
+ *     An optional human-readable message.
  */
 Guacamole.Status = function(code, message) {
 
@@ -42,7 +45,7 @@ Guacamole.Status = function(code, message) {
     /**
      * The Guacamole status code.
      * @see Guacamole.Status.Code
-     * @type Number 
+     * @type {Number}
      */
     this.code = code;
 
@@ -52,7 +55,7 @@ Guacamole.Status = function(code, message) {
      * for debugging purposes only. For user feedback, it is better to translate
      * the Guacamole status code into a message.
      * 
-     * @type String
+     * @type {String}
      */
     this.message = message;
 
@@ -75,44 +78,44 @@ Guacamole.Status.Code = {
     /**
      * The operation succeeded.
      *
-     * @type Number
+     * @type {Number}
      */
     "SUCCESS": 0x0000,
 
     /**
      * The requested operation is unsupported.
      *
-     * @type Number
+     * @type {Number}
      */
     "UNSUPPORTED": 0x0100,
 
     /**
      * The operation could not be performed due to an internal failure.
      *
-     * @type Number
+     * @type {Number}
      */
     "SERVER_ERROR": 0x0200,
 
     /**
      * The operation could not be performed as the server is busy.
      *
-     * @type Number
+     * @type {Number}
      */
     "SERVER_BUSY": 0x0201,
 
-    /**
-     * The operation was unsuccessful due to an error or otherwise unexpected
-     * condition of the upstream server.
-     *
-     * @type Number
-     */
-    "UPSTREAM_TIMEOUT": 0x0202,
-
     /**
      * The operation could not be performed because the upstream server is not
      * responding.
      *
-     * @type Number
+     * @type {Number}
+     */
+    "UPSTREAM_TIMEOUT": 0x0202,
+
+    /**
+     * The operation was unsuccessful due to an error or otherwise unexpected
+     * condition of the upstream server.
+     *
+     * @type {Number}
      */
     "UPSTREAM_ERROR": 0x0203,
 
@@ -120,7 +123,7 @@ Guacamole.Status.Code = {
      * The operation could not be performed as the requested resource does not
      * exist.
      *
-     * @type Number
+     * @type {Number}
      */
     "RESOURCE_NOT_FOUND": 0x0204,
 
@@ -128,14 +131,14 @@ Guacamole.Status.Code = {
      * The operation could not be performed as the requested resource is
      * already in use.
      *
-     * @type Number
+     * @type {Number}
      */
     "RESOURCE_CONFLICT": 0x0205,
 
     /**
      * The operation could not be performed because bad parameters were given.
      *
-     * @type Number
+     * @type {Number}
      */
     "CLIENT_BAD_REQUEST": 0x0300,
 
@@ -143,7 +146,7 @@ Guacamole.Status.Code = {
      * Permission was denied to perform the operation, as the user is not yet
      * authorized (not yet logged in, for example).
      *
-     * @type Number
+     * @type {Number}
      */
     "CLIENT_UNAUTHORIZED": 0x0301,
 
@@ -151,28 +154,28 @@ Guacamole.Status.Code = {
      * Permission was denied to perform the operation, and this permission will
      * not be granted even if the user is authorized.
      *
-     * @type Number
+     * @type {Number}
      */
     "CLIENT_FORBIDDEN": 0x0303,
 
     /**
      * The client took too long to respond.
      *
-     * @type Number
+     * @type {Number}
      */
     "CLIENT_TIMEOUT": 0x0308,
 
     /**
      * The client sent too much data.
      *
-     * @type Number
+     * @type {Number}
      */
     "CLIENT_OVERRUN": 0x030D,
 
     /**
      * The client sent data of an unsupported or unexpected type.
      *
-     * @type Number
+     * @type {Number}
      */
     "CLIENT_BAD_TYPE": 0x030F,
 
@@ -180,7 +183,7 @@ Guacamole.Status.Code = {
      * The operation failed because the current client is already using too
      * many resources.
      *
-     * @type Number
+     * @type {Number}
      */
     "CLIENT_TOO_MANY": 0x031D
 

guacamole-common-js/src/main/webapp/modules/StringReader.js

@@ -42,20 +42,23 @@ Guacamole.StringReader = function(stream) {
     /**
      * Wrapped Guacamole.ArrayBufferReader.
      * @private
-     * @type Guacamole.ArrayBufferReader
+     * @type {Guacamole.ArrayBufferReader}
      */
     var array_reader = new Guacamole.ArrayBufferReader(stream);
 
     /**
      * The number of bytes remaining for the current codepoint.
-     * 
+     *
-     * @type Number
+     * @private
+     * @type {Number}
      */
     var bytes_remaining = 0;
 
     /**
      * The current codepoint value, as calculated from bytes read so far.
-     * @type Number
+     *
+     * @private
+     * @type {Number}
      */
     var codepoint = 0;
 

guacamole-common-js/src/main/webapp/modules/StringWriter.js

@@ -41,7 +41,7 @@ Guacamole.StringWriter = function(stream) {
     /**
      * Wrapped Guacamole.ArrayBufferWriter.
      * @private
-     * @type Guacamole.ArrayBufferWriter
+     * @type {Guacamole.ArrayBufferWriter}
      */
     var array_writer = new Guacamole.ArrayBufferWriter(stream);
 

guacamole-common-js/src/main/webapp/modules/Tunnel.js

@@ -51,15 +51,16 @@ Guacamole.Tunnel = function() {
      * Send the given message through the tunnel to the service on the other
      * side. All messages are guaranteed to be received in the order sent.
      * 
-     * @param {...} elements The elements of the message to send to the
+     * @param {...*} elements
-     *                       service on the other side of the tunnel.
+     *     The elements of the message to send to the service on the other side
+     *     of the tunnel.
      */
     this.sendMessage = function(elements) {};
 
     /**
      * The current state of this tunnel.
      * 
-     * @type Number
+     * @type {Number}
      */
     this.state = Guacamole.Tunnel.State.CONNECTING;
 
@@ -68,7 +69,7 @@ Guacamole.Tunnel = function() {
      * milliseconds. If data is not received within this amount of time,
      * the tunnel is closed with an error. The default value is 15000.
      * 
-     * @type Number
+     * @type {Number}
      */
     this.receiveTimeout = 15000;
 
@@ -110,14 +111,14 @@ Guacamole.Tunnel.State = {
      * A connection is in pending. It is not yet known whether connection was
      * successful.
      * 
-     * @type Number
+     * @type {Number}
      */
     "CONNECTING": 0,
 
     /**
      * Connection was successful, and data is being received.
      * 
-     * @type Number
+     * @type {Number}
      */
     "OPEN": 1,
 
@@ -126,7 +127,7 @@ Guacamole.Tunnel.State = {
      * tunnel may have been explicitly closed by either side, or an error may
      * have occurred.
      * 
-     * @type Number
+     * @type {Number}
      */
     "CLOSED": 2
 
@@ -832,9 +833,10 @@ Guacamole.WebSocketTunnel.prototype = new Guacamole.Tunnel();
  * 
  * @constructor
  * @augments Guacamole.Tunnel
- * @param {...} tunnel_chain The tunnels to use, in order of priority.
+ * @param {...*} tunnelChain
+ *     The tunnels to use, in order of priority.
  */
-Guacamole.ChainedTunnel = function(tunnel_chain) {
+Guacamole.ChainedTunnel = function(tunnelChain) {
 
     /**
      * Reference to this chained tunnel.
@@ -861,7 +863,7 @@ Guacamole.ChainedTunnel = function(tunnel_chain) {
      * has yet been committed.
      *
      * @private
-     * @type Guacamole.Tunnel
+     * @type {Guacamole.Tunnel}
      */
     var committedTunnel = null;
 

guacamole-common-js/src/main/webapp/modules/Version.js

@@ -28,6 +28,6 @@ var Guacamole = Guacamole || {};
  * used in downstream applications as a sanity check that the proper version
  * of the APIs is being used (in case an older version is cached, for example).
  *
- * @type String
+ * @type {String}
  */
 Guacamole.API_VERSION = "0.9.5";