add more documentation

Author: publicarray

HttpRequest.java

@@ -4,6 +4,13 @@
 import java.text.SimpleDateFormat;
 import static SSHelpers.Util.*;
 
+/**
+ * This class contains the needed information (host, port number and all Http headers) for a typical Http Request.
+ *
+ * @author      Modified by: Sebastian Schmidt
+ * @version     1.0 2016-10-18
+ * @since       1.0
+ */
 public class HttpRequest {
     /** Help variables */
     final static String CRLF = "\r\n";
@@ -18,7 +25,14 @@ public class HttpRequest {
     private int port;
     private int error;
 
-    /** Create HttpRequest by reading it from the client socket */
+    /**
+     * Creates a HttpRequest by reading it from the client socket.
+     * The constructor attempts to parse the content form the client.
+     * If there is a error in parsing the client will receive a
+     * 400 (Bad request) error indicating that the request was malformed.
+     * @param  from The content stream from a socket connection.
+     * @return      A new HttpRequest.
+     */
     public HttpRequest(BufferedReader from) {
         error = 0;
         String firstLine = "";
@@ -57,17 +71,25 @@ public HttpRequest(BufferedReader from) {
             }
 
             // TODO: get POST parameters
-            //
-            //
-        } catch (IOException e) {
+
+        } catch (Exception e) {
             error = 400;
-            System.out.println("Error reading from socket: " + e);
+            System.out.println("Error reading from client socket: " + e);
             return;
         }
         System.out.println("Host to contact is: " + host + " at port " + port);
     }
 
-    // constructor
+    /**
+     * Constructs a HttpRequest given the required variables
+     * @param  method  The http method E.g GET or POST
+     * @param  url     The location of the resource E.g. /example.html
+     * @param  version The Http protocol version, usually it is HTTP/1.1
+     * @param  headers Any optional http headers. If you don't want to add any use an empty string ("").
+     * @param  host    The hostname of the server where the request is send to E.g. example.com
+     * @param  port    The port number used for the webs server E.g. 80
+     * @return         A HttpRequet object
+     */
     public HttpRequest(String method, String url, String version, String headers, String host, int port) {
         this.method = method;
         this.URL = url;
@@ -78,7 +100,11 @@ public HttpRequest(String method, String url, String version, String headers, St
         this.error = 0;
     }
 
-    // copy constructor
+    /**
+     * Copy constructor
+     * @param  other An existing HttpRequest to create the copy from
+     * @return       A deep copy of the 'other' HttpRequest
+     */
     public HttpRequest(HttpRequest other) {
         this.method = other.method;
         this.URL = other.URL;

Makefile

@@ -17,7 +17,9 @@ docs: *.java
 	$(JDOC) $^ -d docs \
 		-windowtitle $(DOCTITLE) \
 		-doctitle $(DOCTITLE) \
-		-subpackages SSHelpers
+		-subpackages SSHelpers \
+		-version \
+		-author
 
 docs-clean:
 	$(RM) docs/*

SSHelpers/Util.java

@@ -4,8 +4,16 @@
 import java.util.TimeZone;
 import java.text.ParseException;
 import java.text.SimpleDateFormat;
-
+/**
+ * A utility class containing small helper methods.
+ * These methods can be used my importing the class <code>import static SSHelpers.Util.*;</code>
+ *
+ * @author      Sebastian Schmidt
+ * @version     1.0 2016-10-18
+ * @since       1.0
+ */
 public class Util {
+
     /**
      * From a url string get the host-name
      * @param  url The Url E.g. http://example.com/foo
@@ -88,6 +96,12 @@ public static String getLocation(String url) {
         return url.substring(end);
     }
 
+    /**
+     * Converts a string to a Java date object given the correct format.
+     * @param  dateStr The string that is parsed as a date.
+     * @param  format  The format as defined in the SimpleDateFormat <a href="https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html">https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html</a>.
+     * @return         Returns a new date object. On failure it will return null.
+     */
     public static Date toDate(String dateStr, String format) {
         try {
             SimpleDateFormat inFormat = new SimpleDateFormat(format);
@@ -98,18 +112,33 @@ public static Date toDate(String dateStr, String format) {
         }
         return null;
     }
-
+     /**
+     * Converts a string to a Java date object using "E, dd MMM yyyy HH:mm:ss z" (Mon, 13 Jun 2016 21:06:31 GMT) as the format.
+     * @param  dateStr The string that is parsed as a date.
+     * @return         Returns a new date object. On failure it will return null.
+     */
     public static Date toDate(String dateStr) {
-        String format = "E, dd MMM yyyy HH:mm:ss z"; // Mon, 13 Jun 2016 21:06:31 GMT
+        String format = "E, dd MMM yyyy HH:mm:ss z";
         return Util.toDate(dateStr, format);
     }
 
+    /**
+     * Converts a Java string object to a string with the given format.
+     * @param  date   The date to format.
+     * @param  format The format as defined in the SimpleDateFormat <a href="https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html">https://docs.oracle.com/javase/8/docs/api/java/text/SimpleDateFormat.html</a>.
+     * @return        The date as a string.
+     */
     public static String dateToString(Date date, String format) {
         SimpleDateFormat dateFormat = new SimpleDateFormat (format);
         dateFormat.setTimeZone(TimeZone.getTimeZone("GMT"));
         return dateFormat.format(date);
     }
 
+    /**
+     * Converts a Java string object to a string using "E, dd MMM yyyy HH:mm:ss z" (Mon, 13 Jun 2016 21:06:31 GMT) as the format.
+     * @param  date   The date to format.
+     * @return        The date as a string.
+     */
     public static String dateToString(Date date) {
         return Util.dateToString(date, "E, dd MMM yyyy HH:mm:ss z");
     }