From 68ccf5f170064a1a8751fd591c2809eac52d00d4 Mon Sep 17 00:00:00 2001 From: Michael Jumper Date: Sat, 11 Aug 2012 12:52:30 -0700 Subject: [PATCH] Fix jsdoc, add missing documentation. --- src/main/resources/guacamole.js | 102 +++++++++++++++++++++++++++++++------- src/main/resources/keyboard.js | 19 +++---- src/main/resources/layer.js | 9 +++- src/main/resources/mouse.js | 6 ++- src/main/resources/oskeyboard.js | 94 ++++++++++++++++++++++++++++++----- src/main/resources/tunnel.js | 20 +++++++- 6 files changed, 202 insertions(+), 48 deletions(-) diff --git a/src/main/resources/guacamole.js b/src/main/resources/guacamole.js index 1cf3b94..d566a3d 100644 --- a/src/main/resources/guacamole.js +++ b/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; - guac_client.onname = null; - guac_client.onerror = null; - guac_client.onclipboard = null; + /** + * Fired whenever the state of this Guacamole.Client changes. + * + * @event + * @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 = diff --git a/src/main/resources/keyboard.js b/src/main/resources/keyboard.js index 8c0d3ab..8c08f39 100644 --- a/src/main/resources/keyboard.js +++ b/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; - - return true; + guac_keyboard.onkeydown(keysym); } @@ -350,9 +345,7 @@ Guacamole.Keyboard = function(element) { // Send key event if (keysym != null && guac_keyboard.onkeyup) - return guac_keyboard.onkeyup(keysym) != false; - - return true; + guac_keyboard.onkeyup(keysym); } diff --git a/src/main/resources/layer.js b/src/main/resources/layer.js index 8358fbb..e6052e7 100644 --- a/src/main/resources/layer.js +++ b/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. diff --git a/src/main/resources/mouse.js b/src/main/resources/mouse.js index 55f99b1..9dc2f22 100644 --- a/src/main/resources/mouse.js +++ b/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; diff --git a/src/main/resources/oskeyboard.js b/src/main/resources/oskeyboard.js index 1f8c083..3acebdb 100644 --- a/src/main/resources/oskeyboard.js +++ b/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; -} +}; diff --git a/src/main/resources/tunnel.js b/src/main/resources/tunnel.js index 87155eb..4f75ea3 100644 --- a/src/main/resources/tunnel.js +++ b/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) { -- 1.7.10.4