Filled in some javadocs

Author: jentfoo

client/src/main/java/org/threadly/litesockets/client/http/HTTPClient.java

@@ -658,10 +658,21 @@ public HTTPResponse getResponse() {
       return hr;
     }
 
+    /**
+     * Get the response code sent with the response.
+     * 
+     * @return {@link HTTPResponseCode} sent with the response.
+     */
     public HTTPResponseCode getResponseCode() {
       return hr.getResponseHeader().getResponseCode();
     }
-        
+    
+    /**
+     * Get the length associated with the response based off the header value if available, or the 
+     * size of the body if not.
+     * 
+     * @return The size of the body in bytes
+     */
     public long getContentLength() {
       long result = hr.getHeaders().getContentLength();
       if (result >= 0) {
@@ -671,14 +682,31 @@ public long getContentLength() {
       }
     }
 
+    /**
+     * Get a copy of the body as a {@link MergedByteBuffers}.
+     * 
+     * @return A copy of the body buffers.
+     */
     public MergedByteBuffers getBody() {
       return body.duplicate();
     }
 
+    /**
+     * Converts the entire body into a {@link String}.
+     *  
+     * @return The body as a {@link String}
+     */
     public String getBodyAsString() {
       return body.duplicate().getAsString(body.remaining());
     }
 
+    /**
+     * Returns the body as a {@link InputStream}.  Consuming this stream wont impact the retention 
+     * of the body (still allowing it to be retrieved from {@link #getBody()} and 
+     * {@link #getBodyAsString()}).
+     * 
+     * @return The response body as a stream
+     */
     public InputStream getBodyAsInputStream() {
       return body.duplicate().asInputStream();
     }

client/src/main/java/org/threadly/litesockets/client/http/HTTPStreamClient.java

@@ -183,6 +183,10 @@ public ListenableFuture<?> write(ByteBuffer bb) {
     }
   }
 
+  /**
+   * Get the {@link ListenableFuture} associated with the last write to the associated client.  
+   * This future will complete when the write has been written to the socket.
+   */
   public ListenableFuture<?> getLastWriteFuture() {
     return client.lastWriteFuture();
   }
@@ -229,31 +233,36 @@ public void addCloseListener(Runnable cl) {
     }
   }
 
+  /**
+   * Check if the client is connected.
+   * 
+   * @return {@code true} if the client has not been closed yet
+   */
   public boolean isConnected() {
     return isConnected;
   }
 
+  /**
+   * Close the associated client.
+   */
   public void close() {
     isConnected = false;
     client.close();
   }  
 
   /**
-   * 
-   * @author lwahlmeier
-   *
+   * Implementation of {@link Reader} which will provide the data to the {@code httpProcessor}.
    */
   private class HTTPReader implements Reader {
     @Override
     public void onRead(Client client) {
       httpProcessor.processData(client.getRead());
     }
   }
-  
+
   /**
-   * 
-   * @author lwahlmeier
-   *
+   * Implementation of {@link ClientCloseListener} to communicate the closed status to this class 
+   * and attached listeners.
    */
   private class HTTPCloser implements ClientCloseListener {
     @Override

protocol/src/main/java/org/threadly/litesockets/protocols/http/request/ClientHTTPRequest.java

@@ -4,6 +4,8 @@
 
 import org.threadly.litesockets.protocols.http.shared.HTTPAddress;
 
+// TODO - do we want to move this into the `client`?  I see the `HTTPRequestBuilder` references it, 
+// but we could create an extending class `ClientHTTPRequestBuilder` which can build this
 /**
  * This contains a full HTTPRequest, including the HTTPRequest, the HTTPAddress the body and the timeout.
  * This is immutable, though an HTTPRequestBuilder can be made from it.
@@ -25,18 +27,37 @@ public HTTPRequest getHTTPRequest() {
     return request;
   }
 
+  /**
+   * Returns the {@link HTTPAddress} the request is associated with.
+   * 
+   * @return The {@link HTTPAddress} the request will go to
+   */
   public HTTPAddress getHTTPAddress() {
     return ha;
   }
 
+  // TODO - does this make sense, it seems dangerous since the buffer could be consumed / read.
+  // We could return a slice / duplicate copy to avoid this, or we can change this to `hasBodyContent` 
+  // (which seems how this is being used)
+  /**
+   * Returns the body data the request was constructed with.
+   * 
+   * @return The ByteBuffer representing the body
+   */
   public ByteBuffer getBodyBuffer() {
     return bodyBytes;
   }
 
+  /**
+   * Returns the timeout value that this request was constructed with.
+   * 
+   * @return The request timeout in milliseconds
+   */
   public int getTimeoutMS() {
     return this.timeoutMS;
   }
 
+  // TODO - is this useful?  I am not seeing any cases of it being used
   public HTTPRequestBuilder makeBuilder() {
     HTTPRequestBuilder hrb = request.makeBuilder();
     hrb.setHTTPAddress(ha, false);

protocol/src/main/java/org/threadly/litesockets/protocols/http/request/HTTPRequestHeader.java

@@ -141,6 +141,7 @@ public Map<String, List<String>> getRequestQuery() {
    * Gets the value to a given query parameter.  This will throw an exception if there is multiple 
    * values associated to the key.
    *  
+   * @param paramKey The key associated with the query parameter value
    * @return the request parameter value or {@code null} if none is associated
    */
   public String getRequestQueryValue(String paramKey) {

protocol/src/main/java/org/threadly/litesockets/protocols/http/shared/HTTPHeaders.java

@@ -53,8 +53,13 @@ public HTTPHeaders(final Map<String, String> headerMap) {
     rawHeaders = formatHeaderMap(lheaders);
     this.headers = Collections.unmodifiableMap(lheaders);
   }
-  
 
+  /**
+   * Converts a {@link Map} into the HTTP standard header format.
+   * 
+   * @param headerMap The map to use for input
+   * @return The string of HTTP encoded headers
+   */
   public static String formatHeaderMap(Map<String, String> headerMap) {
     StringBuilder sb = new StringBuilder();
     for(Entry<String, String> kv: headerMap.entrySet()) {
@@ -67,18 +72,41 @@ public static String formatHeaderMap(Map<String, String> headerMap) {
     return sb.toString();
   }
 
+  /**
+   * Get the header key / values as a {@link Map}.
+   * 
+   * @return The header key / values.
+   */
   public Map<String, String> getHeadersMap() {
     return headers;
   }
 
+  /**
+   * Check if the headers are defining this as a chunked request / response.  This is determined 
+   * by the presence of a header key {@link HTTPConstants#HTTP_KEY_TRANSFER_ENCODING}.
+   * 
+   * @return {@code true} if the encoding is set as chunked
+   */
   public boolean isChunked() {
     return headers.containsKey(HTTPConstants.HTTP_KEY_TRANSFER_ENCODING);
   }
 
+  /**
+   * Get the value associated with a key in the headers.
+   * 
+   * @param header The key to use for the header value
+   * @return The header value or {@code null} if no header key match is found
+   */
   public String getHeader(String header) {
     return headers.get(header);
   }
 
+  /**
+   * Parse out the content length from the value of {@link HTTPConstants#HTTP_KEY_CONTENT_LENGTH} 
+   * header.
+   * 
+   * @return The length sent in the header or {@code -1} if none is provided (or failed to parse)
+   */
   public long getContentLength() {
     String scl = headers.get(HTTPConstants.HTTP_KEY_CONTENT_LENGTH);
     long cl = -1;

protocol/src/main/java/org/threadly/litesockets/protocols/http/shared/HTTPResponseCode.java

@@ -76,6 +76,10 @@ private HTTPResponseCode(int val, String text) {
     this.text = text;
   }
 
+  /**
+   * Return the http standard numeric code / id associated to the response code.
+   * @return The id value
+   */
   public int getId() {
     return val;
   }
@@ -85,6 +89,13 @@ public String toString() {
     return text;
   }
 
+  /**
+   * Attempt to convert a response code from a numeric id to an enum value.
+   * 
+   * @param val The value to check for match
+   * @return A matching response code enum
+   * @throws IllegalArgumentException thrown if no code is associated with the provided value
+   */
   public static HTTPResponseCode findResponseCode(int val) {
     for(HTTPResponseCode hrc: HTTPResponseCode.values()) { 
       if(hrc.getId() == val) {

protocol/src/main/java/org/threadly/litesockets/protocols/http/shared/HTTPUtils.java

@@ -12,20 +12,30 @@
 import org.threadly.util.StringUtils;
 
 /**
- * 
- * 
- * @author lwahlmeier
- *
+ * Utility functions for working with the HTTP protocol.
  */
 public class HTTPUtils {
+  /**
+   * Trim whitespace from the left side of the String only.
+   * 
+   * @param value String to trim from
+   * @return A left-trimmed string
+   */
   public static String leftTrim(String value) {
     int count = 0;
-    while(Character.isWhitespace(value.charAt(count))) {
+    while(value.length() > count && Character.isWhitespace(value.charAt(count))) {
       count++;
     }
     return value.substring(count);
   }
 
+  /**
+   * Used for parsing a chunk encoded request / response.  This will find the end of the chunk 
+   * and then parse out the size of the next chunk
+   * 
+   * @param bb Source {@link ByteBuffer} to read from
+   * @return The next chunk size or {@code -1} if could not be found or failed to parse
+   */
   public static int getNextChunkLength(final ByteBuffer bb) {
     MergedByteBuffers mbb = new ReuseableMergedByteBuffers();
     mbb.add(bb);
@@ -41,6 +51,12 @@ public static int getNextChunkLength(final ByteBuffer bb) {
     return -1;
   }
 
+  /**
+   * Wraps the given data in a chunk to be used for chunked encoding.
+   * 
+   * @param bb The data to wrap
+   * @return A new buffer which wraps the data in a chunk encoded segment
+   */
   public static ByteBuffer wrapInChunk(ByteBuffer bb) {
     byte[] size = Integer.toHexString(bb.remaining()).getBytes();
     ByteBuffer newBB = ByteBuffer.allocate(bb.remaining()+
@@ -53,6 +69,12 @@ public static ByteBuffer wrapInChunk(ByteBuffer bb) {
     return newBB;
   }
 
+  /**
+   * Converts query parameters stored in a map to a {@link String} that can be added to the URI.
+   * 
+   * @param map Map to source the values from
+   * @return HTTP standard query parameters, prefixed with {@code ?}
+   */
   public static String queryToString(Map<String, List<String>> map) {
     if(map.isEmpty()) {
       return "";
@@ -82,6 +104,12 @@ public static String queryToString(Map<String, List<String>> map) {
     return sb.toString();
   }
 
+  /**
+   * Parses http standard query parameters from the URL into a {@link Map} representation.
+   * 
+   * @param query The String to parse
+   * @return The parsed our parameters into a {@link Map}
+   */
   public static Map<String, List<String>> queryToMap(String query) {
     if (StringUtils.isNullOrEmpty(query)) {
       return Collections.emptyMap();

protocol/src/main/java/org/threadly/litesockets/protocols/websocket/WSConstants.java

@@ -1,5 +1,8 @@
 package org.threadly.litesockets.protocols.websocket;
 
+/**
+ * Constants used for websockets.
+ */
 public class WSConstants {
   public static final String MAGIC_UUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"; 
   public static final int DEFAULT_SECRET_KEY_SIZE = 20;

protocol/src/main/java/org/threadly/litesockets/protocols/websocket/WSFrame.java

@@ -88,7 +88,7 @@ public boolean hasMask() {
   }
 
   /**
-   * Returns the size of the websocket frames payload
+   * Returns the size of the websocket frames payload.
    * 
    * @return size of the payload.
    */

protocol/src/main/java/org/threadly/litesockets/protocols/websocket/WSOPCode.java

@@ -2,22 +2,32 @@
 
 /**
  * Standard Websocket OpCodes.
- * 
  */
 public enum WSOPCode {
   Continuation((byte)0), Text((byte)1), Binary((byte)2),
   Close((byte)8), Ping((byte)9), Pong((byte)10); 
 
   private final byte value;
 
-  WSOPCode(byte value) {
+  private WSOPCode(byte value) {
     this.value = value;
   }
 
+  /**
+   * Get the opcode value.
+   * 
+   * @return The standard value associated with the opcode
+   */
   public byte getValue() {
     return value;
   }
 
+  /**
+   * Convert a op code byte to an {@link WSOPCode} enum value.
+   * 
+   * @param b Byte to check against
+   * @return Matching opcode or {@code null} if none was found
+   */
   public static WSOPCode fromByte(byte b) {
     for(WSOPCode oc: WSOPCode.values()) {
       if(oc.getValue() == b) {