Adding appropriate comments on classes and full description in App.java. Removing added function in ServiceAmbassador as it's not appropriate for the example.

ambassador/src/main/java/com/iluwatar/ambassador/App.java

@@ -1,5 +1,44 @@
+/**
+ * The MIT License
+ * Copyright (c) 2014-2016 Ilkka Seppälä
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
 package com.iluwatar.ambassador;
 
+/**
+ *
+ * The ambassador pattern creates a helper service that sends network requests on behalf of a
+ * client. It is often used in cloud-based applications to offload features of a remote service.
+ *
+ * An ambassador service can be thought of as an out-of-process proxy that is co-located with
+ * the client. Similar to the proxy design pattern, the ambassador service provides an interface
+ * for another remote service. In addition to the interface, the ambassador provides extra
+ * functionality and features, specifically offloaded common connectivity tasks. This usually
+ * consists of monitoring, logging, routing, security etc. This is extremely useful in
+ * legacy applications where the codebase is difficult to modify and allows for improvements
+ * in the application's networking capabilities.
+ *
+ * In this example, we will the ({@link ServiceAmbassador}) class represents the ambassador while the
+ * ({@link RemoteService}) class represents a remote application.
+ *
+ */
 public class App {
 
     /**
@@ -9,11 +48,7 @@ public class App {
 
         Client host1 = new Client();
         Client host2 = new Client();
-
         host1.useService(12);
         host2.useService(73);
-
-        host1.useNewService(12);
-        host2.useNewService(73);
     }
 }

ambassador/src/main/java/com/iluwatar/ambassador/Client.java

@@ -22,6 +22,9 @@
  */
 package com.iluwatar.ambassador;
 
+/**
+ * A simple Client
+ */
 public class Client {
 
     private ServiceAmbassador serviceAmbassador;
@@ -34,9 +37,4 @@ public class Client {
         long result = serviceAmbassador.doRemoteFunction(value);
         System.out.println(result);
     }
-
-    void useNewService(int value) {
-        long result = serviceAmbassador.doAddedFunction(value);
-        System.out.println(result);
-    }
 }

ambassador/src/main/java/com/iluwatar/ambassador/RemoteService.java

@@ -24,6 +24,9 @@ package com.iluwatar.ambassador;
 
 import static java.lang.Thread.sleep;
 
+/**
+ * A remote legacy application represented by a Singleton implementation.
+ */
 public class RemoteService implements RemoteServiceInterface {
 
     private static RemoteService service = null;
@@ -39,6 +42,12 @@ public class RemoteService implements RemoteServiceInterface {
 
     }
 
+    /**
+     * Remote function takes a value and multiplies it by 10 taking a random amount of time.
+     * Will sometimes return -1. This immitates connectivity issues a client might have to account for.
+     * @param value integer value to be multiplied.
+     * @return if waitTime is more than 200ms, it returns value * 10, otherwise -1.
+     */
     @Override
     public long doRemoteFunction(int value) {
 

ambassador/src/main/java/com/iluwatar/ambassador/RemoteServiceInterface.java

@@ -22,6 +22,9 @@
  */
 package com.iluwatar.ambassador;
 
+/**
+ * Interface shared by ({@link RemoteService}) and ({@link ServiceAmbassador}).
+ */
 interface RemoteServiceInterface {
 
     long doRemoteFunction(int value) throws Exception;

ambassador/src/main/java/com/iluwatar/ambassador/ServiceAmbassador.java

@@ -27,6 +27,13 @@ import org.slf4j.LoggerFactory;
 
 import static java.lang.Thread.sleep;
 
+/**
+ *
+ * ServiceAmbassador provides an interface for a ({@link Client}) to access ({@link RemoteService}).
+ * The interface adds logging, latency testing and usage of the service in a safe way that will not
+ * add stress to the remote service when connectivity issues occur.
+ *
+ */
 public class ServiceAmbassador implements RemoteServiceInterface {
 
     private static final Logger LOGGER = LoggerFactory.getLogger(ServiceAmbassador.class);
@@ -43,10 +50,6 @@ public class ServiceAmbassador implements RemoteServiceInterface {
         return safeCall(value);
     }
 
-    long doAddedFunction(int value) {
-        return safeCall(value) * 5;
-    }
-
     private long checkLatency(int value) {
         RemoteService service = RemoteService.getRemoteService();
         long startTime = System.currentTimeMillis();