Merge pull request #421 from Massive-Dynamics/websocket-util-doc

Redid documentation for WebSocketUtil

codec-http/src/main/java/io/netty/handler/codec/http/websocketx/WebSocketUtil.java

@@ -19,90 +19,91 @@ import io.netty.buffer.ByteBuf;
 import io.netty.buffer.Unpooled;
 import io.netty.handler.codec.base64.Base64;
 import io.netty.util.CharsetUtil;
-
 import java.security.MessageDigest;
 import java.security.NoSuchAlgorithmException;
 
 /**
- * TODO Document me.
+ * A utility class mainly for use by web sockets
  */
 final class WebSocketUtil {
 
     /**
-     * Performs an MD5 hash
+     * Performs a MD5 hash on the specified data
      *
-     * @param bytes
+     * @param data The data to hash
-     *            Data to hash
+     * @return The hashed data
-     * @return Hashed data
      */
-    static byte[] md5(byte[] bytes) {
+    static byte[] md5(byte[] data) {
         try {
+            //Try to get a MessageDigest that uses MD5
             MessageDigest md = MessageDigest.getInstance("MD5");
-            return md.digest(bytes);
+            //Hash the data
+            return md.digest(data);
         } catch (NoSuchAlgorithmException e) {
-            throw new InternalError("MD5 not supported on this platform");
+            //This shouldn't happen! How old is the computer?
+            throw new InternalError("MD5 not supported on this platform - Outdated?");
         }
     }
 
     /**
-     * Performs an SHA-1 hash
+     * Performs a SHA-1 hash on the specified data
      *
-     * @param bytes
+     * @param data The data to hash
-     *            Data to hash
+     * @return The hashed data
-     * @return Hashed data
      */
-    static byte[] sha1(byte[] bytes) {
+    static byte[] sha1(byte[] data) {
         try {
+            //Attempt to get a MessageDigest that uses SHA1
             MessageDigest md = MessageDigest.getInstance("SHA1");
-            return md.digest(bytes);
+            //Hash the data
+            return md.digest(data);
         } catch (NoSuchAlgorithmException e) {
-            throw new InternalError("SHA-1 not supported on this platform");
+            //Alright, you might have an old system.
+            throw new InternalError("SHA-1 is not supported on this platform - Outdated?");
         }
     }
 
     /**
-     * Base 64 encoding
+     * Performs base64 encoding on the specified data
      *
-     * @param bytes
+     * @param data The data to encode
-     *            Bytes to encode
+     * @return An encoded string containing the data
-     * @return encoded string
      */
-    static String base64(byte[] bytes) {
+    static String base64(byte[] data) {
-        ByteBuf hashed = Unpooled.wrappedBuffer(bytes);
+        ByteBuf encodedData = Unpooled.wrappedBuffer(data);
-        return Base64.encode(hashed).toString(CharsetUtil.UTF_8);
+        return Base64.encode(encodedData).toString(CharsetUtil.UTF_8);
     }
 
     /**
-     * Creates some random bytes
+     * Creates an arbitrary number of random bytes
      *
-     * @param size
+     * @param size the number of random bytes to create
-     *            Number of random bytes to create
+     * @return An array of random bytes
-     * @return random bytes
      */
     static byte[] randomBytes(int size) {
         byte[] bytes = new byte[size];
 
-        for (int i = 0; i < size; i++) {
+        for (int index = 0; index < size; index++) {
-            bytes[i] = (byte) randomNumber(0, 255);
+            bytes[index] = (byte) randomNumber(0, 255);
         }
 
         return bytes;
     }
 
     /**
-     * Generates a random number
+     * Generates a pseudo-random number
      *
-     * @param min
+     * @param minimum The minimum allowable value
-     *            Minimum value
+     * @param maximum The maximum allowable value
-     * @param max
+     * @return A pseudo-random number
-     *            Maximum value
-     * @return Random number
      */
-    static int randomNumber(int min, int max) {
+    static int randomNumber(int minimum, int maximum) {
-        return (int) (Math.random() * max + min);
+        return (int) (Math.random() * maximum + minimum);
     }
 
-
+    /**
+     * A private constructor to ensure that instances of this class cannot be made
+     */
     private WebSocketUtil() {
         // Unused
     }