Javadoc cleanup and make the service APIs consistent

java/client/src/main/java/com/cloudera/kitten/client/YarnClientService.java

@@ -20,15 +20,31 @@
 import com.google.common.util.concurrent.Service;
 
 /**
- * Writing your own YARN Client is for suckers. Use this service instead.
+ * A {@code Service} that handles the client-side logic for the lifecycle of a typical
+ * YARN application.
  */
 public interface YarnClientService extends Service {
 
+  /**
+   * Returns the parameters used to configure this service.
+   */
   YarnClientParameters getParameters();
 
+  /**
+   * Returns the ID of the application once it has been submitted. Only valid
+   * while the service is in the RUNNING state.
+   */
   ApplicationId getApplicationId();
 
+  /**
+   * Queries the YARN resource manager for the current state of the application on
+   * the cluster and returns the result.
+   */
   ApplicationReport getApplicationReport();
 
+  /**
+   * Check to see whether or not the application is still executing on the
+   * cluster.
+   */
   boolean isApplicationFinished();
 }

java/master/src/main/java/com/cloudera/kitten/appmaster/ApplicationMasterParameters.java

@@ -22,28 +22,63 @@
 import com.cloudera.kitten.ContainerLaunchParameters;
 
 /**
- * The information that the {@link ApplicationMasterService} needs to know in order to
+ * The information that the {@code ApplicationMasterService} needs to know in order to
  * setup and manage a YARN application.
  */
 public interface ApplicationMasterParameters {
 
+  /**
+   * Returns the {@code Configuration} instance that should be used for this run.
+   */
   Configuration getConfiguration();
 
+  /**
+   * Returns the attempt ID for this application.
+   */
   ApplicationAttemptId getApplicationAttemptId();
 
+  /**
+   * Returns the parameters that will be used to launch the child containers for
+   * this application.
+   */
   List<ContainerLaunchParameters> getContainerLaunchParameters();
 
+  /**
+   * Returns the number of containers that are allowed to fail before this
+   * application shuts itself down automatically.
+   */
   int getAllowedFailures();
 
+  /**
+   * Sets the hostname the master is running on. This information is communicated to the
+   * resource manager and is then passed along to the client by YARN.
+   */
   ApplicationMasterParameters setHostname(String hostname);
 
+  /**
+   * Returns the hostname that was set for this application master.
+   */
   String getHostname();
 
+  /**
+   * Sets the port the master is listening on for client requests. This information is
+   * communicated to the resource manager and is then passed along to the client by YARN.
+   */
   ApplicationMasterParameters setClientPort(int port);
 
+  /**
+   * Returns the client port that was set for this application master.
+   */
   int getClientPort();
 
+  /**
+   * Sets a tracking URL for the client. If it is not specified, the combination of the
+   * hostname and the client port will be used.
+   */
   ApplicationMasterParameters setTrackingUrl(String url);
-
+
+  /**
+   * Returns the tracking URL that was set for this application master.
+   */
   String getTrackingUrl();  
 }

java/master/src/main/java/com/cloudera/kitten/appmaster/ApplicationMasterService.java

@@ -19,9 +19,18 @@
 import com.google.common.util.concurrent.Service;
 
 /**
- * Writing your own ApplicationMaster is for suckers. Use this service instead.
+ * A service that handles the common cluster-side logic for running an application on YARN. It
+ * should be included in the same JAR file that contains the application's business logic.
  */
 public interface ApplicationMasterService extends Service {
 
+  /**
+   * Returns the parameters used to configure this service.
+   */
+  ApplicationMasterParameters getParameters();
+
+  /**
+   * Returns the application attempt ID.
+   */
   ApplicationAttemptId getApplicationAttemptId();
 }

java/master/src/main/java/com/cloudera/kitten/appmaster/service/ApplicationMasterServiceImpl.java

@@ -87,6 +87,11 @@ public ApplicationMasterServiceImpl(ApplicationMasterParameters parameters,
     this.containerTrackers = Lists.newArrayList();
   }
 
+  @Override
+  public ApplicationMasterParameters getParameters() {
+    return parameters;
+  }
+
   @Override
   public ApplicationAttemptId getApplicationAttemptId() {
     return parameters.getApplicationAttemptId();