Update the Client file documentation (#111)

Author: vinifarias

src/main/java/com/sendgrid/Client.java

@@ -26,7 +26,10 @@
 import org.apache.http.impl.client.CloseableHttpClient;
 import org.apache.http.impl.client.HttpClients;
 
-// Hack to get DELETE to accept a request body
+
+/**
+ * Hack to get DELETE to accept a request body.
+ */
 class HttpDeleteWithBody extends HttpEntityEnclosingRequestBase {
 	public static final String METHOD_NAME = "DELETE";
 
@@ -41,6 +44,7 @@ public HttpDeleteWithBody(final String uri) {
 	}
 }
 
+
 /**
  * Class Client allows for quick and easy access any REST or REST-like API.
  */
@@ -50,6 +54,7 @@ public class Client implements Closeable {
 	private Boolean test;
 	private boolean createdHttpClient;
 
+
 	/**
 	 * Constructor for using the default CloseableHttpClient.
 	 */
@@ -59,6 +64,7 @@ public Client() {
 		this.createdHttpClient = true;
 	}
 
+
 	/**
 	 * Constructor for passing in an httpClient, typically for mocking. Passed-in httpClient will not be closed
 	 * by this Client.
@@ -70,8 +76,9 @@ public Client(CloseableHttpClient httpClient) {
 		this(httpClient, false);
 	}
 
+
 	/**
-	 * Constructor for passing in a test parameter to allow for http calls
+	 * Constructor for passing in a test parameter to allow for http calls.
 	 *
 	 * @param test
 	 *            is a Bool
@@ -80,8 +87,9 @@ public Client(Boolean test) {
 		this(HttpClients.createDefault(), test);
 	}
 
+
 	/**
-	 * Constructor for passing in a  an httpClient and test parameter to allow for http calls
+	 * Constructor for passing in an httpClient and test parameter to allow for http calls.
 	 *
 	 * @param httpClient
 	 *            an Apache CloseableHttpClient
@@ -104,6 +112,8 @@ public Client(CloseableHttpClient httpClient, Boolean test) {
 	 *            (e.g. "/your/endpoint/path")
 	 * @param queryParams
 	 *            map of key, values representing the query parameters
+	 * @throws URISyntaxException
+	 *            in of a URI syntax error
 	 */
 	public URI buildUri(String baseUri, String endpoint, Map<String, String> queryParams) throws URISyntaxException {
 		URIBuilder builder = new URIBuilder();
@@ -133,11 +143,15 @@ public URI buildUri(String baseUri, String endpoint, Map<String, String> queryPa
 		return uri;
 	}
 
+
 	/**
 	 * Prepare a Response object from an API call via Apache's HTTP client.
 	 *
 	 * @param response
 	 *            from a call to a CloseableHttpClient
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
 	 */
 	public Response getResponse(CloseableHttpResponse response) throws IOException {
 		ResponseHandler<String> handler = new SendGridResponseHandler();
@@ -154,9 +168,18 @@ public Response getResponse(CloseableHttpResponse response) throws IOException {
 		return new Response(statusCode, responseBody, responseHeaders);
 	}
 
+
 	/**
 	 * Make a GET request and provide the status code, response body and
 	 * response headers.
+	 * 
+	 * @param request 
+	 *            the request object
+	 * @throws URISyntaxException
+	 *            in case of a URI syntax error
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
 	 */
 	public Response get(Request request) throws URISyntaxException, IOException {
 		URI uri = null;
@@ -177,9 +200,18 @@ public Response get(Request request) throws URISyntaxException, IOException {
 		return executeApiCall(httpGet);
 	}
 
+
 	/**
 	 * Make a POST request and provide the status code, response body and
 	 * response headers.
+	 *
+	 * @param request 
+	 *            the request object
+	 * @throws URISyntaxException
+	 *            in case of a URI syntax error
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
 	 */
 	public Response post(Request request) throws URISyntaxException, IOException {
 		URI uri = null;
@@ -204,9 +236,18 @@ public Response post(Request request) throws URISyntaxException, IOException {
 		return executeApiCall(httpPost);
 	}
 
+
 	/**
 	 * Make a PATCH request and provide the status code, response body and
 	 * response headers.
+	 *
+	 * @param request 
+	 *            the request object
+	 * @throws URISyntaxException
+	 *            in case of a URI syntax error
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
 	 */
 	public Response patch(Request request) throws URISyntaxException, IOException {
 		URI uri = null;
@@ -231,9 +272,18 @@ public Response patch(Request request) throws URISyntaxException, IOException {
 		return executeApiCall(httpPatch);
 	}
 
+
 	/**
 	 * Make a PUT request and provide the status code, response body and
 	 * response headers.
+	 *
+	 * @param request 
+	 *            the request object
+	 * @throws URISyntaxException
+	 *            in case of a URI syntax error
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
 	 */
 	public Response put(Request request) throws URISyntaxException, IOException {
 		URI uri = null;
@@ -258,8 +308,17 @@ public Response put(Request request) throws URISyntaxException, IOException {
 		return executeApiCall(httpPut);
 	}
 
+
 	/**
 	 * Make a DELETE request and provide the status code and response headers.
+	 *
+	 * @param request 
+	 *            the request object
+	 * @throws URISyntaxException
+	 *            in case of a URI syntax error
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
 	 */
 	public Response delete(Request request) throws URISyntaxException, IOException {
 		URI uri = null;
@@ -290,6 +349,16 @@ private void writeContentTypeIfNeeded(Request request, HttpMessage httpMessage)
 		}
 	}
 
+
+	/**
+	 * Makes a call to the client API.
+	 *
+	 * @param httpPost 
+	 *            the request method object
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
+	 */
 	private Response executeApiCall(HttpRequestBase httpPost) throws IOException {
 		try {
 			CloseableHttpResponse serverResponse = httpClient.execute(httpPost);
@@ -303,8 +372,15 @@ private Response executeApiCall(HttpRequestBase httpPost) throws IOException {
 		}
 	}
 
+
 	/**
 	 * A thin wrapper around the HTTP methods.
+	 *
+	 * @param request 
+	 *            the request object
+	 * @throws IOException
+	 *            in case of a network error
+	 * @return the response object
 	 */
 	public Response api(Request request) throws IOException {
 		try {
@@ -334,11 +410,25 @@ public Response api(Request request) throws IOException {
 		}
 	}
 
+
+	/**
+	 * Closes the http client.
+	 *
+	 * @throws IOException
+	 *            in case of a network error
+	 */	
 	@Override
 	public void close() throws IOException {
       	this.httpClient.close();
 	}
 
+
+	/**
+	 * Closes and finalizes the http client.
+	 *
+	 * @throws Throwable
+	 *            in case of an error
+	 */		
 	@Override
 	public void finalize() throws Throwable {
 		try {