GUACAMOLE-422: Update documentation and style; tweaks to GuacamoleProtocolVersion implementation.

guacamole-common/src/main/java/org/apache/guacamole/protocol/ConfiguredGuacamoleSocket.java

@@ -153,7 +153,7 @@ public class ConfiguredGuacamoleSocket implements GuacamoleSocket {
             
             // Check for protocol version as first argument
             if (i == 0 && arg_name.startsWith("VERSION_")) {
-                protocol = GuacamoleProtocolVersion.valueOf(arg_name);
+                protocol = GuacamoleProtocolVersion.getVersion(arg_name);
                 arg_values[i] = protocol.toString();
                 continue;
             }

guacamole-common/src/main/java/org/apache/guacamole/protocol/GuacamoleClientInformation.java

@@ -151,7 +151,8 @@ public class GuacamoleClientInformation {
     }
     
     /**
-     * Return the timezone as reported by the client.
+     * Return the timezone as reported by the client, or an empty String if
+     * one is not set.
      * 
      * @return
      *     A string value of the timezone reported by the client.

guacamole-common/src/main/java/org/apache/guacamole/protocol/GuacamoleProtocolVersion.java

@@ -19,9 +19,6 @@
 
 package org.apache.guacamole.protocol;
 
-import org.apache.guacamole.GuacamoleException;
-import org.apache.guacamole.GuacamoleUnsupportedException;
-
 /**
  * An enum that defines the available Guacamole protocol versions that can be
  * used between guacd and clients, and provides convenience methods for parsing
@@ -29,19 +26,35 @@ import org.apache.guacamole.GuacamoleUnsupportedException;
  */
 public enum GuacamoleProtocolVersion {
     
-    // Version 1.0.0 and older.
+    /**
+     * Protocol version 1.0.0 and older.  Any client that doesn't explicitly
+     * set the protocol version will negotiate down to this protocol version.
+     * This requires that handshake instructions be ordered correctly, and
+     * lacks support for certain protocol-related features introduced in later
+     * versions.
+     */
     VERSION_1_0_0(1, 0, 0),
 
-    // Version 1.1.0
+    /**
+     * Protocol version 1.1.0, which introduces Client-Server version
+     * detection, arbitrary handshake instruction order, and support
+     * for passing the client timezone to the server during the handshake.
+     */
     VERSION_1_1_0(1, 1, 0);
     
-    // The major version number.
+    /**
+     * The major version component of the protocol version.
+     */
     private final int major;
 
-    // The minor version number.
+    /**
+     * The minor version component of the protocol version.
+     */
     private final int minor;
 
-    // The patch version number.
+    /**
+     * The patch version component of the protocol version.
+     */
     private final int patch;
     
     /**
@@ -139,4 +152,24 @@ public enum GuacamoleProtocolVersion {
         
     }
     
+    /**
+     * Parse the String format of the version provided and return the
+     * the enum value matching that version.  If no value is provided, return
+     * null.
+     * 
+     * @param version
+     *     The String format of the version to parse.
+     * 
+     * @return
+     *     The enum value that matches the specified version.
+     */
+    public static GuacamoleProtocolVersion getVersion(String version) {
+        
+        if (version == null || version.isEmpty())
+            return null;
+        
+        return valueOf(version);
+        
+    }
+    
 }

guacamole/src/main/java/org/apache/guacamole/tunnel/TunnelRequest.java

@@ -372,11 +372,11 @@ public abstract class TunnelRequest {
     }
     
     /**
-     * Returns the value of the timezone parameter declared within the
-     * tunnel request.
+     * Returns the tz database value of the timezone declared by the client
+     * within the tunnel request.
      * 
      * @return 
-     *     The string value of the timezone parameter as reported by
+     *     The tz database value of the timezone parameter as reported by
      *     the client.
      */
     public String getTimezone() {

guacamole/src/main/webapp/app/settings/services/preferenceService.js

@@ -104,7 +104,8 @@ angular.module('settings').provider('preferenceService', ['$injector',
      * by the JSTZ timezone library.
      * 
      * @returns String
-     *     The name of the currently-detected timezone.
+     *     The name of the currently-detected timezone in tz database
+     *     format.
      */
     var getDetectedTimezone = function getDetectedTimezone() {
         return jstz.determine().name();