Fix jsdoc, add missing documentation.

guacamole-common-js/src/main/resources/guacamole.js

@@ -36,7 +36,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-// Guacamole namespace
+/**
+ * Namespace for all Guacamole JavaScript objects.
+ * @namespace
+ */
 var Guacamole = Guacamole || {};
 
 
@@ -71,6 +74,7 @@ Guacamole.Client = function(tunnel) {
 
     /**
      * Translation from Guacamole protocol line caps to Layer line caps.
+     * @private
      */
     var lineCap = {
         0: "butt",
@@ -80,6 +84,7 @@ Guacamole.Client = function(tunnel) {
 
     /**
      * Translation from Guacamole protocol line caps to Layer line caps.
+     * @private
      */
     var lineJoin = {
         0: "bevel",
@@ -175,11 +180,27 @@ Guacamole.Client = function(tunnel) {
 
     }
 
-    guac_client.getDisplay = function() {
+    /**
+     * Returns an element containing the display of this Guacamole.Client.
+     * Adding the element returned by this function to an element in the body
+     * of a document will cause the client's display to be visible.
+     * 
+     * @return {Element} An element containing ths display of this
+     *                   Guacamole.Client.
+     */
+    this.getDisplay = function() {
         return bounds;
     };
 
-    guac_client.sendKeyEvent = function(pressed, keysym) {
+    /**
+     * Sends a key event having the given properties as if the user
+     * pressed or released a key.
+     * 
+     * @param {Boolean} pressed Whether the key is pressed (true) or released
+     *                          (false).
+     * @param {Number} keysym The keysym of the key being pressed or released.
+     */
+    this.sendKeyEvent = function(pressed, keysym) {
         // Do not send requests if not connected
         if (!isConnected())
             return;
@@ -187,7 +208,14 @@ Guacamole.Client = function(tunnel) {
         tunnel.sendMessage("key", keysym, pressed);
     };
 
-    guac_client.sendMouseState = function(mouseState) {
+    /**
+     * Sends a mouse event having the properties provided by the given mouse
+     * state.
+     * 
+     * @param {Guacamole.Mouse.State} mouseState The state of the mouse to send
+     *                                           in the mouse event.
+     */
+    this.sendMouseState = function(mouseState) {
 
         // Do not send requests if not connected
         if (!isConnected())
@@ -211,7 +239,12 @@ Guacamole.Client = function(tunnel) {
         tunnel.sendMessage("mouse", Math.floor(mouseState.x), Math.floor(mouseState.y), buttonMask);
     };
 
-    guac_client.setClipboard = function(data) {
+    /**
+     * Sets the clipboard of the remote client to the given text data.
+     * 
+     * @param {String} data The data to send as the clipboard contents.
+     */
+    this.setClipboard = function(data) {
 
         // Do not send requests if not connected
         if (!isConnected())
@@ -220,11 +253,38 @@ Guacamole.Client = function(tunnel) {
         tunnel.sendMessage("clipboard", data);
     };
 
-    // Handlers
+    /**
-    guac_client.onstatechange = null;
+     * Fired whenever the state of this Guacamole.Client changes.
-    guac_client.onname = null;
+     * 
-    guac_client.onerror = null;
+     * @event
-    guac_client.onclipboard = null;
+     * @param {Number} state The new state of the client.
+     */
+    this.onstatechange = null;
+
+    /**
+     * Fired when the remote client sends a name update.
+     * 
+     * @event
+     * @param {String} name The new name of this client.
+     */
+    this.onname = null;
+
+    /**
+     * Fired when an error is reported by the remote client, and the connection
+     * is being closed.
+     * 
+     * @event
+     * @param {String} error A human-readable description of the error.
+     */
+    this.onerror = null;
+
+    /**
+     * Fired when the clipboard of the remote client is changing.
+     * 
+     * @event
+     * @param {String} data The new text data of the remote clipboard.
+     */
+    this.onclipboard = null;
 
     // Layers
     function getBufferLayer(index) {
@@ -281,6 +341,7 @@ Guacamole.Client = function(tunnel) {
 
     /**
      * Handlers for all defined layer properties.
+     * @private
      */
     var layerPropertyHandlers = {
 
@@ -293,6 +354,7 @@ Guacamole.Client = function(tunnel) {
     /**
      * Handlers for all instruction opcodes receivable by a Guacamole protocol
      * client.
+     * @private
      */
     var instructionHandlers = {
 
@@ -793,7 +855,7 @@ Guacamole.Client = function(tunnel) {
     };
 
 
-    guac_client.disconnect = function() {
+    this.disconnect = function() {
 
         // Only attempt disconnection not disconnected.
         if (currentState != STATE_DISCONNECTED
@@ -814,7 +876,7 @@ Guacamole.Client = function(tunnel) {
 
     };
     
-    guac_client.connect = function(data) {
+    this.connect = function(data) {
 
         setState(STATE_CONNECTING);
 
@@ -834,7 +896,7 @@ Guacamole.Client = function(tunnel) {
         setState(STATE_WAITING);
     };
 
-    guac_client.scale = function(scale) {
+    this.scale = function(scale) {
 
         display.style.transform =
         display.style.WebkitTransform =
@@ -852,7 +914,7 @@ Guacamole.Client = function(tunnel) {
 
     };
 
-    guac_client.getScale = function() {
+    this.getScale = function() {
         return displayScale;
     };
 
@@ -901,7 +963,7 @@ Guacamole.Client.LayerContainer = function(width, height) {
      * @param {Number} width The new width to assign to this Layer.
      * @param {Number} height The new height to assign to this Layer.
      */
-    layer_container.resize = function(width, height) {
+    this.resize = function(width, height) {
 
         // Resize layer
         layer.resize(width, height);
@@ -916,7 +978,7 @@ Guacamole.Client.LayerContainer = function(width, height) {
      * Returns the Layer contained within this LayerContainer.
      * @returns {Guacamole.Layer} The Layer contained within this LayerContainer.
      */
-    layer_container.getLayer = function() {
+    this.getLayer = function() {
         return layer;
     };
 
@@ -924,17 +986,19 @@ Guacamole.Client.LayerContainer = function(width, height) {
      * Returns the element containing the Layer within this LayerContainer.
      * @returns {Element} The element containing the Layer within this LayerContainer.
      */
-    layer_container.getElement = function() {
+    this.getElement = function() {
         return div;
     };
 
     /**
      * The translation component of this LayerContainer's transform.
+     * @private
      */
     var translate = "translate(0px, 0px)"; // (0, 0)
 
     /**
      * The arbitrary matrix component of this LayerContainer's transform.
+     * @private
      */
     var matrix = "matrix(1, 0, 0, 1, 0, 0)"; // Identity
 
@@ -945,7 +1009,7 @@ Guacamole.Client.LayerContainer = function(width, height) {
      * @param {Number} x The X coordinate to move to.
      * @param {Number} y The Y coordinate to move to.
      */
-    layer_container.translate = function(x, y) {
+    this.translate = function(x, y) {
 
         // Generate translation
         translate = "translate("
@@ -974,7 +1038,7 @@ Guacamole.Client.LayerContainer = function(width, height) {
      * @param {Number} e The fifth value in the affine transform's matrix.
      * @param {Number} f The sixth value in the affine transform's matrix.
      */
-    layer_container.transform = function(a, b, c, d, e, f) {
+    this.transform = function(a, b, c, d, e, f) {
 
         // Generate matrix transformation
         matrix =

guacamole-common-js/src/main/resources/keyboard.js

@@ -35,7 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-// Guacamole namespace
+/**
+ * Namespace for all Guacamole JavaScript objects.
+ * @namespace
+ */
 var Guacamole = Guacamole || {};
 
 /**
@@ -60,9 +63,6 @@ Guacamole.Keyboard = function(element) {
      * 
      * @event
      * @param {Number} keysym The keysym of the key being pressed.
-     * @returns {Boolean} true if the originating event of this keypress should
-     *                    be allowed through to the browser, false or undefined
-     *                    otherwise.
      */
     this.onkeydown = null;
 
@@ -72,9 +72,6 @@ Guacamole.Keyboard = function(element) {
      * 
      * @event
      * @param {Number} keysym The keysym of the key being released.
-     * @returns {Boolean} true if the originating event of this key release 
-     *                    should be allowed through to the browser, false or
-     *                    undefined otherwise.
      */
     this.onkeyup = null;
 
@@ -336,9 +333,7 @@ Guacamole.Keyboard = function(element) {
 
         // Send key event
         if (keysym != null && guac_keyboard.onkeydown)
-            return guac_keyboard.onkeydown(keysym) != false;
+            guac_keyboard.onkeydown(keysym);
-        
-        return true;
 
     }
 
@@ -350,9 +345,7 @@ Guacamole.Keyboard = function(element) {
 
         // Send key event
         if (keysym != null && guac_keyboard.onkeyup)
-            return guac_keyboard.onkeyup(keysym) != false;
+            guac_keyboard.onkeyup(keysym);
-
-        return true;
 
     }
 

guacamole-common-js/src/main/resources/layer.js

@@ -35,7 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-// Guacamole namespace
+/**
+ * Namespace for all Guacamole JavaScript objects.
+ * @namespace
+ */
 var Guacamole = Guacamole || {};
 
 /**
@@ -85,6 +88,7 @@ Guacamole.Layer = function(width, height) {
     /**
      * Whether a new path should be started with the next path drawing
      * operations.
+     * @private
      */
     var pathClosed = true;
 
@@ -94,6 +98,8 @@ Guacamole.Layer = function(width, height) {
      * Note that there will ALWAYS be one element on the stack, but that
      * element is not exposed. It is only used to reset the layer to its
      * initial state.
+     * 
+     * @private
      */
     var stackSize = 0;
 
@@ -323,6 +329,7 @@ Guacamole.Layer = function(width, height) {
      * as whether the task is blocked depends completely on whether the
      * other layer is currently ready.
      * 
+     * @private
      * @param {Guacamole.Layer} otherLayer The other layer which must be blocked
      *                          until this task completes.
      * @param {function} handler The function to call when possible.

guacamole-common-js/src/main/resources/mouse.js

@@ -35,7 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-// Guacamole namespace
+/**
+ * Namespace for all Guacamole JavaScript objects.
+ * @namespace
+ */
 var Guacamole = Guacamole || {};
 
 /**
@@ -103,6 +106,7 @@ Guacamole.Mouse = function(element) {
     /**
      * Counter of mouse events to ignore. This decremented by mousemove, and
      * while non-zero, mouse events will have no effect.
+     * @private
      */
     var ignore_mouse = 0;
 

guacamole-common-js/src/main/resources/oskeyboard.js

@@ -35,7 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-// Guacamole namespace
+/**
+ * Namespace for all Guacamole JavaScript objects.
+ * @namespace
+ */
 var Guacamole = Guacamole || {};
 
 /**
@@ -50,24 +53,48 @@ Guacamole.OnScreenKeyboard = function(url) {
 
     var on_screen_keyboard = this;
 
+    /**
+     * State of all modifiers. This is the bitwise OR of all active modifier
+     * values.
+     * 
+     * @private
+     */
+    var modifiers = 0;
+
     var scaledElements = [];
     
     var modifiers = {};
     var currentModifier = 1;
 
-    // Function for adding a class to an element
+    /**
+     * Adds a class to an element.
+     * 
+     * @private
+     * @function
+     * @param {Element} element The element to add a class to.
+     * @param {String} classname The name of the class to add.
+     */
     var addClass;
 
-    // Function for removing a class from an element
+    /**
+     * Removes a class from an element.
+     * 
+     * @private
+     * @function
+     * @param {Element} element The element to remove a class from.
+     * @param {String} classname The name of the class to remove.
+     */
     var removeClass;
 
     // If Node.classList is supported, implement addClass/removeClass using that
     if (Node.classList) {
 
+        /** @ignore */
         addClass = function(element, classname) {
             element.classList.add(classname);
         };
         
+        /** @ignore */
         removeClass = function(element, classname) {
             element.classList.remove(classname);
         };
@@ -77,6 +104,7 @@ Guacamole.OnScreenKeyboard = function(url) {
     // Otherwise, implement own
     else {
 
+        /** @ignore */
         addClass = function(element, classname) {
 
             // Simply add new class
@@ -84,6 +112,7 @@ Guacamole.OnScreenKeyboard = function(url) {
 
         };
         
+        /** @ignore */
         removeClass = function(element, classname) {
 
             // Filter out classes with given name
@@ -315,7 +344,7 @@ Guacamole.OnScreenKeyboard = function(url) {
                             addClass(key_element, "guac-keyboard-pressed");
 
                             // Get current cap based on modifier state
-                            var cap = key.getCap(on_screen_keyboard.modifiers);
+                            var cap = key.getCap(modifiers);
 
                             // Update modifier state
                             if (cap.modifier) {
@@ -325,10 +354,10 @@ Guacamole.OnScreenKeyboard = function(url) {
                                 var modifierFlag = getModifier(cap.modifier);
 
                                 // Toggle modifier state
-                                on_screen_keyboard.modifiers ^= modifierFlag;
+                                modifiers ^= modifierFlag;
 
                                 // Activate modifier if pressed
-                                if (on_screen_keyboard.modifiers & modifierFlag) {
+                                if (modifiers & modifierFlag) {
                                     
                                     addClass(keyboard, modifierClass);
                                     
@@ -370,7 +399,7 @@ Guacamole.OnScreenKeyboard = function(url) {
                         if (key.pressed) {
 
                             // Get current cap based on modifier state
-                            var cap = key.getCap(on_screen_keyboard.modifiers);
+                            var cap = key.getCap(modifiers);
 
                             removeClass(key_element, "guac-keyboard-pressed");
 
@@ -458,17 +487,37 @@ Guacamole.OnScreenKeyboard = function(url) {
     };
 
     /**
-     * State of all modifiers.
+     * Fired whenever the user presses a key on this Guacamole.OnScreenKeyboard.
+     * 
+     * @event
+     * @param {Number} keysym The keysym of the key being pressed.
      */
-    this.modifiers = 0;
-
     this.onkeydown = null;
+
+    /**
+     * Fired whenever the user releases a key on this Guacamole.OnScreenKeyboard.
+     * 
+     * @event
+     * @param {Number} keysym The keysym of the key being released.
+     */
     this.onkeyup   = null;
 
+    /**
+     * Returns the element containing the entire on-screen keyboard.
+     * @returns {Element} The element containing the entire on-screen keyboard.
+     */
     this.getElement = function() {
         return keyboard;
     };
 
+    /**
+     * Resizes all elements within this Guacamole.OnScreenKeyboard such that
+     * the width is close to but does not exceed the specified width. The
+     * height of the keyboard is determined based on the width.
+     * 
+     * @param {Number} width The width to resize this Guacamole.OnScreenKeyboard
+     *                       to, in pixels.
+     */
     this.resize = function(width) {
 
         // Get pixel size of a unit
@@ -484,6 +533,15 @@ Guacamole.OnScreenKeyboard = function(url) {
 
 };
 
+
+/**
+ * Basic representation of a single key of a keyboard. Each key has a set of
+ * caps associated with tuples of modifiers. The cap determins what happens
+ * when a key is pressed, while it is the state of modifier keys that determines
+ * what cap is in effect on any particular key.
+ * 
+ * @constructor
+ */
 Guacamole.OnScreenKeyboard.Key = function() {
 
     var key = this;
@@ -516,8 +574,20 @@ Guacamole.OnScreenKeyboard.Key = function() {
         return key.caps[modifier & key.modifierMask];
     };
 
-}
+};
 
+/**
+ * Basic representation of a cap of a key. The cap is the visible part of a key
+ * and determines the active behavior of a key when pressed. The state of all
+ * modifiers on the keyboard determines the active cap for all keys, thus
+ * each cap is associated with a set of modifiers.
+ * 
+ * @constructor
+ * @param {String} text The text to be displayed within this cap.
+ * @param {Number} keysym The keysym this cap sends when its associated key is
+ *                        pressed or released.
+ * @param {String} modifier The modifier represented by this cap.
+ */
 Guacamole.OnScreenKeyboard.Cap = function(text, keysym, modifier) {
     
     /**
@@ -538,4 +608,4 @@ Guacamole.OnScreenKeyboard.Cap = function(text, keysym, modifier) {
     // Set modifier if provided
     if (modifier) this.modifier = modifier;
     
-}
+};

guacamole-common-js/src/main/resources/tunnel.js

@@ -35,7 +35,10 @@
  *
  * ***** END LICENSE BLOCK ***** */
 
-// Guacamole namespace
+/**
+ * Namespace for all Guacamole JavaScript objects.
+ * @namespace
+ */
 var Guacamole = Guacamole || {};
 
 /**
@@ -104,6 +107,7 @@ Guacamole.HTTPTunnel = function(tunnelURL) {
 
     /**
      * Reference to this HTTP tunnel.
+     * @private
      */
     var tunnel = this;
 
@@ -142,6 +146,7 @@ Guacamole.HTTPTunnel = function(tunnelURL) {
          * Converts the given value to a length/string pair for use as an
          * element in a Guacamole instruction.
          * 
+         * @private
          * @param value The value to convert.
          * @return {String} The converted value. 
          */
@@ -484,17 +489,20 @@ Guacamole.WebSocketTunnel = function(tunnelURL) {
 
     /**
      * Reference to this WebSocket tunnel.
+     * @private
      */
     var tunnel = this;
 
     /**
      * The WebSocket used by this tunnel.
+     * @private
      */
     var socket = null;
 
     /**
      * The WebSocket protocol corresponding to the protocol used for the current
      * location.
+     * @private
      */
     var ws_protocol = {
         "http:":  "ws:",
@@ -568,6 +576,7 @@ Guacamole.WebSocketTunnel = function(tunnelURL) {
          * Converts the given value to a length/string pair for use as an
          * element in a Guacamole instruction.
          * 
+         * @private
          * @param value The value to convert.
          * @return {String} The converted value. 
          */
@@ -700,23 +709,27 @@ Guacamole.ChainedTunnel = function(tunnel_chain) {
 
     /**
      * Reference to this chained tunnel.
+     * @private
      */
     var chained_tunnel = this;
 
     /**
      * The currently wrapped tunnel, if any.
+     * @private
      */
     var current_tunnel = null;
 
     /**
      * Data passed in via connect(), to be used for
      * wrapped calls to other tunnels' connect() functions.
+     * @private
      */
     var connect_data;
 
     /**
      * Array of all tunnels passed to this ChainedTunnel through the
      * constructor arguments.
+     * @private
      */
     var tunnels = [];
 
@@ -725,7 +738,10 @@ Guacamole.ChainedTunnel = function(tunnel_chain) {
         tunnels.push(arguments[i]);
 
     /**
-     * Sets the current tunnel
+     * Sets the current tunnel.
+     * 
+     * @private
+     * @param {Guacamole.Tunnel} tunnel The tunnel to set as the current tunnel.
      */
     function attach(tunnel) {