Docs updates for the advanced options in OpenTok.Builder

Author: jeffswartz

README.md

@@ -69,13 +69,39 @@ String apiSecret = "YOUR API SECRET";
 OpenTok opentok = new OpenTok(apiKey, apiSecret)
 ```
 
-#### Additional Configurations
-`.requestTimeout(int)` - Change the default HTTP request timeout, default is 60 seconds.
-`.apiUrl(String)` - Change the domain that the SDK points to. Useful when needing to select a specific datacenter or point to a mock version of the API for testing.
-`.proxy(Proxy)` - Using a `Proxy` object, you can configure a proxy server that the http client should use when accessing the OpenTok URLs.
+#### Advanced configuration options
 
+You can use `OpenTok.Builder` to set advanced options. This class
+includes the following methods:
 
-And make sure you call `close` when you are done to prevent leaked file descriptors.
+- `.requestTimeout(int)` -- Call this to specify the timeout for HTTP requests
+  (in seconds). The default timeout is 60 seconds.
+
+- `.proxy(Proxy)` -- Using a `java.net.Proxy` object, you can configure a proxy server
+  that the HTTP client will use when call the OpenTok REST API.
+
+Call the `OpenTok.Builder()` constructor, passing in your API key and secret,
+to instantiate an `OpenTok.Builder` object. Then call the `requestTimeout()`
+or `proxy()` methods (or both). Then call the `build()` method to return an
+OpenTok object. 
+
+For example, the following code instantiates an OpenTok object, with the
+default timeout set to 10 seconds:
+
+```java
+int apiKey = 12345; // YOUR API KEY
+String apiSecret = "YOUR API SECRET";
+int timeout = 10;
+
+OpenTok opentok = new OpenTok.Builder(apiKey, apiSecret)
+  .requestTimeout(timeout)
+  .build();
+```
+
+#### The close() method
+
+Make sure you call the `OpenTok.close()` method when you are done,
+to prevent leaked file descriptors:
 
 ```java
 opentok.close();

src/main/java/com/opentok/OpenTok.java

@@ -699,6 +699,14 @@ public Sip dial(String sessionId, String token, SipProperties properties) throws
             throw new RequestException("Exception mapping json: " + e.getMessage());
         }
     }
+
+    /**
+     * Used to create an OpenTok object with advanced settings. You can set
+     * the request timeout for API calls and a proxy to use for API calls.
+     * <p>
+     * If you do not need to set these advanced settings, you can use the
+     * {@link OpenTok OpenTok()} constructor to build the OpenTok object.
+     */
     public static class Builder {
         private int apiKey;
         private String apiSecret;
@@ -708,22 +716,42 @@ public static class Builder {
         private String principal;
         private String password;
         private int requestTimeout;
-        
+
+        /**
+         * Constructs a new OpenTok.Builder object.
+         *
+         * @param apiKey The API key for your OpenTok project.
+         * 
+         * @param apiSecret The API secret for your OpenTok project. You can obtain
+         * your API key and secret from your <a href="https://tokbox.com/account">Video API account</a>.
+         * Do not publicly share your API secret. 
+         */
         public Builder(int apiKey, String apiSecret) {
             this.apiKey = apiKey;
             this.apiSecret = apiSecret;
         }
-        
+
+        /**
+         * Do not use. This method is used by Vonage for testing.
+         */
         public Builder apiUrl(String apiUrl) {
             this.apiUrl = apiUrl;
             return this;
         }
-        
+
+        /**
+         * Sets a proxy server that the HTTP client will use when making calls to
+         * the OpenTok REST API.
+         */
         public Builder proxy(Proxy proxy) {
             proxy(proxy, null, null, null);
             return this;
         }
 
+        /**
+         * Specify the timeout for HTTP requests (in seconds). The default
+         * timeout is 60 seconds.
+         */
         public Builder requestTimeout(int requestTimeout) {
             this.requestTimeout = requestTimeout * 1000;
             return this;
@@ -736,7 +764,13 @@ public Builder proxy(Proxy proxy, ProxyAuthScheme proxyAuthScheme, String princi
             this.password = password;
             return this;
         }
-        
+
+        /**
+         * Builds the OpenTok object with the settings provided to this
+         * Builder object.
+         *
+         * @return The OpenTok object.
+         */
         public OpenTok build() {
             HttpClient.Builder clientBuilder = new HttpClient.Builder(apiKey, apiSecret);
 
@@ -754,6 +788,10 @@ public OpenTok build() {
         }
     }
 
+    /**
+     * Call this method when you are done using the OpenTok object,
+     * to prevent leaked file descriptors.
+     */
     public void close() {
         client.close();
     }