GUACAMOLE-986: Update documentation of all parameters/returns to specify non-nullable and/or primitive types where appropriate.

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

@@ -25,8 +25,8 @@ var Guacamole = Guacamole || {};
  * provided tunnel, updating its display using one or more canvas elements.
  * 
  * @constructor
- * @param {Guacamole.Tunnel} tunnel The tunnel to use to send and receive
- *                                  Guacamole instructions.
+ * @param {!Guacamole.Tunnel} tunnel
+ *     The tunnel to use to send and receive Guacamole instructions.
  */
 Guacamole.Client = function(tunnel) {
 
@@ -46,7 +46,9 @@ Guacamole.Client = function(tunnel) {
 
     /**
      * Translation from Guacamole protocol line caps to Layer line caps.
+     *
      * @private
+     * @type {!Object.<number, string>}
      */
     var lineCap = {
         0: "butt",
@@ -56,7 +58,9 @@ Guacamole.Client = function(tunnel) {
 
     /**
      * Translation from Guacamole protocol line caps to Layer line caps.
+     *
      * @private
+     * @type {!Object.<number, string>}
      */
     var lineJoin = {
         0: "bevel",
@@ -68,7 +72,7 @@ Guacamole.Client = function(tunnel) {
      * The underlying Guacamole display.
      *
      * @private
-     * @type {Guacamole.Display}
+     * @type {!Guacamole.Display}
      */
     var display = new Guacamole.Display();
 
@@ -76,7 +80,7 @@ Guacamole.Client = function(tunnel) {
      * All available layers and buffers
      *
      * @private
-     * @type {Object.<Number, (Guacamole.Display.VisibleLayer|Guacamole.Layer)>}
+     * @type {!Object.<number, (Guacamole.Display.VisibleLayer|Guacamole.Layer)>}
      */
     var layers = {};
     
@@ -85,7 +89,7 @@ Guacamole.Client = function(tunnel) {
      * be empty, but audio players may be allocated by the server upon request.
      *
      * @private
-     * @type {Object.<Number, Guacamole.AudioPlayer>}
+     * @type {!Object.<number, Guacamole.AudioPlayer>}
      */
     var audioPlayers = {};
 
@@ -94,7 +98,7 @@ Guacamole.Client = function(tunnel) {
      * be empty, but video players may be allocated by the server upon request.
      *
      * @private
-     * @type {Object.<Number, Guacamole.VideoPlayer>}
+     * @type {!Object.<number, Guacamole.VideoPlayer>}
      */
     var videoPlayers = {};
 
@@ -109,7 +113,7 @@ Guacamole.Client = function(tunnel) {
      * Guacamole server.
      *
      * @private
-     * @type {Guacamole.Object[]}
+     * @type {!Guacamole.Object[]}
      */
     var objects = [];
 
@@ -138,7 +142,7 @@ Guacamole.Client = function(tunnel) {
      * effectively an independent, compressed snapshot of protocol and display
      * state. Invoking this function implicitly flushes the display.
      *
-     * @param {function} callback
+     * @param {!function} callback
      *     Callback which should be invoked once the state object is ready. The
      *     state object will be passed to the callback as the sole parameter.
      *     This callback may be invoked immediately, or later as the display
@@ -207,7 +211,7 @@ Guacamole.Client = function(tunnel) {
      * object from a prior call to exportState(). The Guacamole.Client instance
      * used to export that state need not be the same as this instance.
      *
-     * @param {Object} state
+     * @param {!object} state
      *     An opaque representation of Guacamole.Client state from a prior call
      *     to exportState().
      *
@@ -280,8 +284,8 @@ Guacamole.Client = function(tunnel) {
      * contains an Element which can be added to the DOM, causing the
      * display to become visible.
      * 
-     * @return {Guacamole.Display} The underlying display of this
-     *                             Guacamole.Client.
+     * @return {!Guacamole.Display}
+     *     The underlying display of this Guacamole.Client.
      */
     this.getDisplay = function() {
         return display;
@@ -290,8 +294,11 @@ Guacamole.Client = function(tunnel) {
     /**
      * Sends the current size of the screen.
      * 
-     * @param {Number} width The width of the screen.
-     * @param {Number} height The height of the screen.
+     * @param {!number} width
+     *     The width of the screen.
+     *
+     * @param {!number} height
+     *     The height of the screen.
      */
     this.sendSize = function(width, height) {
 
@@ -307,9 +314,11 @@ Guacamole.Client = function(tunnel) {
      * 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.
+     * @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
@@ -323,10 +332,10 @@ Guacamole.Client = function(tunnel) {
      * Sends a mouse event having the properties provided by the given mouse
      * state.
      * 
-     * @param {Guacamole.Mouse.State} mouseState
+     * @param {!Guacamole.Mouse.State} mouseState
      *     The state of the mouse to send in the mouse event.
      *
-     * @param {Boolean} [applyDisplayScale=false]
+     * @param {boolean} [applyDisplayScale=false]
      *     Whether the provided mouse state uses local display units, rather
      *     than remote display units, and should be scaled to match the
      *     {@link Guacamole.Display}.
@@ -368,10 +377,10 @@ Guacamole.Client = function(tunnel) {
      * Sends a touch event having the properties provided by the given touch
      * state.
      *
-     * @param {Guacamole.Touch.State} touchState
+     * @param {!Guacamole.Touch.State} touchState
      *     The state of the touch contact to send in the touch event.
      *
-     * @param {Boolean} [applyDisplayScale=false]
+     * @param {boolean} [applyDisplayScale=false]
      *     Whether the provided touch state uses local display units, rather
      *     than remote display units, and should be scaled to match the
      *     {@link Guacamole.Display}.
@@ -426,7 +435,7 @@ Guacamole.Client = function(tunnel) {
      * mimetype will be sent along the returned stream. The instruction
      * necessary to create this stream will automatically be sent.
      *
-     * @param {String} mimetype
+     * @param {!string} mimetype
      *     The mimetype of the audio data that will be sent along the returned
      *     stream.
      *
@@ -447,9 +456,14 @@ Guacamole.Client = function(tunnel) {
      * filename. The instruction necessary to create this stream will
      * automatically be sent.
      *
-     * @param {String} mimetype The mimetype of the file being sent.
-     * @param {String} filename The filename of the file being sent.
-     * @return {!Guacamole.OutputStream} The created file stream.
+     * @param {!string} mimetype
+     *     The mimetype of the file being sent.
+     *
+     * @param {!string} filename
+     *     The filename of the file being sent.
+     *
+     * @return {!Guacamole.OutputStream}
+     *     The created file stream.
      */
     this.createFileStream = function(mimetype, filename) {
 
@@ -464,9 +478,14 @@ Guacamole.Client = function(tunnel) {
      * Opens a new pipe for writing, having the given name and mimetype. The
      * instruction necessary to create this stream will automatically be sent.
      *
-     * @param {String} mimetype The mimetype of the data being sent.
-     * @param {String} name The name of the pipe.
-     * @return {!Guacamole.OutputStream} The created file stream.
+     * @param {!string} mimetype
+     *     The mimetype of the data being sent.
+     *
+     * @param {!string} name
+     *     The name of the pipe.
+     *
+     * @return {!Guacamole.OutputStream}
+     *     The created file stream.
      */
     this.createPipeStream = function(mimetype, name) {
 
@@ -481,9 +500,14 @@ Guacamole.Client = function(tunnel) {
      * Opens a new clipboard object for writing, having the given mimetype. The
      * instruction necessary to create this stream will automatically be sent.
      *
-     * @param {String} mimetype The mimetype of the data being sent.
-     * @param {String} name The name of the pipe.
-     * @return {!Guacamole.OutputStream} The created file stream.
+     * @param {!string} mimetype
+     *     The mimetype of the data being sent.
+     *
+     * @param {!string} name
+     *     The name of the pipe.
+     *
+     * @return {!Guacamole.OutputStream}
+     *     The created file stream.
      */
     this.createClipboardStream = function(mimetype) {
 
@@ -501,13 +525,13 @@ Guacamole.Client = function(tunnel) {
      * of the following stream. The instruction necessary to create this stream
      * will automatically be sent.
      *
-     * @param {String} mimetype
+     * @param {!string} mimetype
      *     The mimetype of the data being sent.
      *
-     * @param {String} name
+     * @param {!string} name
      *     The name of the connection parameter to attempt to update.
      *
-     * @return {Guacamole.OutputStream}
+     * @return {!Guacamole.OutputStream}
      *     The created argument value stream.
      */
     this.createArgumentValueStream = function createArgumentValueStream(mimetype, name) {
@@ -525,14 +549,14 @@ Guacamole.Client = function(tunnel) {
      * dictated by the object itself. The instruction necessary to create this
      * stream will automatically be sent.
      *
-     * @param {Number} index
+     * @param {!number} index
      *     The index of the object for which the output stream is being
      *     created.
      *
-     * @param {String} mimetype
+     * @param {!string} mimetype
      *     The mimetype of the data which will be sent to the output stream.
      *
-     * @param {String} name
+     * @param {!string} name
      *     The defined name of an output stream within the given object.
      *
      * @returns {!Guacamole.OutputStream}
@@ -552,11 +576,11 @@ Guacamole.Client = function(tunnel) {
      * Requests read access to the input stream having the given name. If
      * successful, a new input stream will be created.
      *
-     * @param {Number} index
+     * @param {!number} index
      *     The index of the object from which the input stream is being
      *     requested.
      *
-     * @param {String} name
+     * @param {!string} name
      *     The name of the input stream to request.
      */
     this.requestObjectInputStream = function requestObjectInputStream(index, name) {
@@ -571,11 +595,14 @@ Guacamole.Client = function(tunnel) {
     /**
      * Acknowledge receipt of a blob on the stream with the given index.
      * 
-     * @param {Number} index The index of the stream associated with the
-     *                       received blob.
-     * @param {String} message A human-readable message describing the error
-     *                         or status.
-     * @param {Number} code The error code, if any, or 0 for success.
+     * @param {!number} index
+     *     The index of the stream associated with the received blob.
+     *
+     * @param {!string} message
+     *     A human-readable message describing the error or status.
+     *
+     * @param {!number} code
+     *     The error code, if any, or 0 for success.
      */
     this.sendAck = function(index, message, code) {
 
@@ -589,8 +616,11 @@ Guacamole.Client = function(tunnel) {
     /**
      * Given the index of a file, writes a blob of data to that file.
      * 
-     * @param {Number} index The index of the file to write to.
-     * @param {String} data Base64-encoded data to write to the file.
+     * @param {!number} index
+     *     The index of the file to write to.
+     *
+     * @param {!string} data
+     *     Base64-encoded data to write to the file.
      */
     this.sendBlob = function(index, data) {
 
@@ -607,7 +637,7 @@ Guacamole.Client = function(tunnel) {
      * stream is closed, and the index will be made available for reuse in
      * future streams.
      * 
-     * @param {Number} index
+     * @param {!number} index
      *     The index of the stream to end.
      */
     this.endStream = function(index) {
@@ -631,7 +661,8 @@ Guacamole.Client = function(tunnel) {
      * Fired whenever the state of this Guacamole.Client changes.
      * 
      * @event
-     * @param {Number} state The new state of the client.
+     * @param {!number} state
+     *     The new state of the client.
      */
     this.onstatechange = null;
 
@@ -639,7 +670,8 @@ Guacamole.Client = function(tunnel) {
      * Fired when the remote client sends a name update.
      * 
      * @event
-     * @param {String} name The new name of this client.
+     * @param {!string} name
+     *     The new name of this client.
      */
     this.onname = null;
 
@@ -648,8 +680,8 @@ Guacamole.Client = function(tunnel) {
      * is being closed.
      * 
      * @event
-     * @param {Guacamole.Status} status A status object which describes the
-     *                                  error.
+     * @param {!Guacamole.Status} status
+     *     A status object which describes the error.
      */
     this.onerror = null;
 
@@ -658,10 +690,10 @@ Guacamole.Client = function(tunnel) {
      * handler will contain its own event handlers for received data.
      *
      * @event
-     * @param {Guacamole.InputStream} stream
+     * @param {!Guacamole.InputStream} stream
      *     The stream that will receive audio data from the server.
      *
-     * @param {String} mimetype
+     * @param {!string} mimetype
      *     The mimetype of the audio data which will be received.
      *
      * @return {Guacamole.AudioPlayer}
@@ -677,15 +709,15 @@ Guacamole.Client = function(tunnel) {
      * handler will contain its own event handlers for received data.
      *
      * @event
-     * @param {Guacamole.InputStream} stream
+     * @param {!Guacamole.InputStream} stream
      *     The stream that will receive video data from the server.
      *
-     * @param {Guacamole.Display.VisibleLayer} layer
+     * @param {!Guacamole.Display.VisibleLayer} layer
      *     The destination layer on which the received video data should be
      *     played. It is the responsibility of the Guacamole.VideoPlayer
      *     implementation to play the received data within this layer.
      *
-     * @param {String} mimetype
+     * @param {!string} mimetype
      *     The mimetype of the video data which will be received.
      *
      * @return {Guacamole.VideoPlayer}
@@ -701,10 +733,10 @@ Guacamole.Client = function(tunnel) {
      * multi-touch support provided by a particular display layer.
      *
      * @event
-     * @param {Guacamole.Display.VisibleLayer} layer
+     * @param {!Guacamole.Display.VisibleLayer} layer
      *     The layer whose multi-touch support level is being declared.
      *
-     * @param {Number} touches
+     * @param {!number} touches
      *     The maximum number of simultaneous touches supported by the given
      *     layer, where 0 indicates that touch events are not supported at all.
      */
@@ -715,14 +747,14 @@ Guacamole.Client = function(tunnel) {
      * by the server.
      *
      * @event
-     * @param {Guacamole.InputStream} stream
+     * @param {!Guacamole.InputStream} stream
      *     The stream that will receive connection parameter data from the
      *     server.
      *
-     * @param {String} mimetype
+     * @param {!string} mimetype
      *     The mimetype of the data which will be received.
      *
-     * @param {String} name
+     * @param {!string} name
      *     The name of the connection parameter whose value is being exposed.
      */
     this.onargv = null;
@@ -731,9 +763,11 @@ Guacamole.Client = function(tunnel) {
      * Fired when the clipboard of the remote client is changing.
      * 
      * @event
-     * @param {Guacamole.InputStream} stream The stream that will receive
-     *                                       clipboard data from the server.
-     * @param {String} mimetype The mimetype of the data which will be received.
+     * @param {!Guacamole.InputStream} stream
+     *     The stream that will receive clipboard data from the server.
+     *
+     * @param {!string} mimetype
+     *     The mimetype of the data which will be received.
      */
     this.onclipboard = null;
 
@@ -742,10 +776,14 @@ Guacamole.Client = function(tunnel) {
      * handler will contain its own event handlers for received data.
      * 
      * @event
-     * @param {Guacamole.InputStream} stream The stream that will receive data
-     *                                       from the server.
-     * @param {String} mimetype The mimetype of the file received.
-     * @param {String} filename The name of the file received.
+     * @param {!Guacamole.InputStream} stream
+     *     The stream that will receive data from the server.
+     *
+     * @param {!string} mimetype
+     *     The mimetype of the file received.
+     *
+     * @param {!string} filename
+     *     The name of the file received.
      */
     this.onfile = null;
 
@@ -755,10 +793,10 @@ Guacamole.Client = function(tunnel) {
      * requesting and handling data.
      *
      * @event
-     * @param {Guacamole.Object} object
+     * @param {!Guacamole.Object} object
      *     The created filesystem object.
      *
-     * @param {String} name
+     * @param {!string} name
      *     The name of the filesystem.
      */
     this.onfilesystem = null;
@@ -768,10 +806,14 @@ Guacamole.Client = function(tunnel) {
      * handler will contain its own event handlers for received data;
      * 
      * @event
-     * @param {Guacamole.InputStream} stream The stream that will receive data
-     *                                       from the server.
-     * @param {String} mimetype The mimetype of the data which will be received.
-     * @param {String} name The name of the pipe.
+     * @param {!Guacamole.InputStream} stream
+     *     The stream that will receive data from the server.
+     *
+     * @param {!string} mimetype
+     *     The mimetype of the data which will be received.
+     *
+     * @param {!string} name
+     *     The name of the pipe.
      */
     this.onpipe = null;
     
@@ -781,7 +823,7 @@ Guacamole.Client = function(tunnel) {
      * continue, such as user credentials.
      * 
      * @event
-     * @param {String[]} parameters
+     * @param {!string[]} parameters
      *      The names of the connection parameters that are required to be
      *      provided for the connection to continue.
      */
@@ -793,8 +835,8 @@ Guacamole.Client = function(tunnel) {
      * has sent any results.
      * 
      * @event
-     * @param {Number} timestamp The timestamp associated with the sync
-     *                           instruction.
+     * @param {!number} timestamp
+     *     The timestamp associated with the sync instruction.
      */
     this.onsync = null;
 
@@ -804,10 +846,10 @@ Guacamole.Client = function(tunnel) {
      * the default layer, and negative indices refer to buffers.
      *
      * @private
-     * @param {Number} index
+     * @param {!number} index
      *     The index of the layer to retrieve.
      *
-     * @return {Guacamole.Display.VisibleLayer|Guacamole.Layer}
+     * @return {!(Guacamole.Display.VisibleLayer|Guacamole.Layer)}
      *     The layer having the given index.
      */
     var getLayer = function getLayer(index) {
@@ -838,10 +880,10 @@ Guacamole.Client = function(tunnel) {
      * Positive indices refer to visible layers, an index of zero refers to the
      * default layer, and negative indices refer to buffers.
      *
-     * @param {Guacamole.Display.VisibleLayer|Guacamole.Layer} layer
+     * @param {!(Guacamole.Display.VisibleLayer|Guacamole.Layer)} layer
      *     The layer whose index should be determined.
      *
-     * @returns {Number}
+     * @returns {number}
      *     The index of the given layer, or null if no such layer is associated
      *     with this client.
      */
@@ -880,7 +922,9 @@ Guacamole.Client = function(tunnel) {
 
     /**
      * Handlers for all defined layer properties.
+     *
      * @private
+     * @type {!Object.<string, function>}
      */
     var layerPropertyHandlers = {
 
@@ -901,7 +945,9 @@ Guacamole.Client = function(tunnel) {
     /**
      * Handlers for all instruction opcodes receivable by a Guacamole protocol
      * client.
+     *
      * @private
+     * @type {!Object.<string, function>}
      */
     var instructionHandlers = {
 
@@ -1629,9 +1675,12 @@ Guacamole.Client = function(tunnel) {
      * Connects the underlying tunnel of this Guacamole.Client, passing the
      * given arbitrary data to the tunnel during the connection process.
      *
-     * @param data Arbitrary connection data to be sent to the underlying
-     *             tunnel during the connection process.
-     * @throws {Guacamole.Status} If an error occurs during connection.
+     * @param {string} data
+     *     Arbitrary connection data to be sent to the underlying tunnel during
+     *     the connection process.
+     *
+     * @throws {!Guacamole.Status}
+     *     If an error occurs during connection.
      */
     this.connect = function(data) {
 
@@ -1657,7 +1706,9 @@ Guacamole.Client = function(tunnel) {
 
 /**
  * Map of all Guacamole binary raster operations to transfer functions.
+ *
  * @private
+ * @type {!Object.<number, function>}
  */
 Guacamole.Client.DefaultTransferFunction = {