From f0c0a094fffd324c276ee7e7cb2eebf803bd7a8d Mon Sep 17 00:00:00 2001
From: Mahadev Konar <mahadev@apache.org>
Date: Sun, 27 Nov 2011 23:17:09 +0000
Subject: [PATCH] MAPREDUCE-3371. Review and improve the yarn-api javadocs.
 (Ravi Prakash via mahadev) - Merging r1206899 from trunk.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/branches/branch-0.23@1206909 13f79535-47bb-0310-9956-ffa450edef68
---
 hadoop-mapreduce-project/CHANGES.txt          |  3 ++
 .../apache/hadoop/yarn/api/AMRMProtocol.java  |  4 +-
 .../hadoop/yarn/api/ClientRMProtocol.java     |  5 ++-
 .../hadoop/yarn/api/ContainerManager.java     |  9 ++--
 .../api/protocolrecords/AllocateRequest.java  | 11 +++--
 .../api/protocolrecords/AllocateResponse.java |  2 +-
 .../GetAllApplicationsRequest.java            |  2 +
 .../GetClusterMetricsRequest.java             |  2 +
 .../GetClusterNodesRequest.java               |  2 +
 .../GetClusterNodesResponse.java              |  2 +-
 .../GetContainerStatusResponse.java           |  2 +-
 .../GetNewApplicationRequest.java             |  2 +
 .../GetNewApplicationResponse.java            |  2 +-
 .../GetQueueUserAclsInfoRequest.java          |  2 +
 .../StartContainerResponse.java               | 42 +++++++++++++++++++
 .../StopContainerResponse.java                |  2 +
 .../SubmitApplicationResponse.java            |  2 +
 .../hadoop/yarn/api/records/AMResponse.java   |  4 +-
 .../yarn/api/records/ApplicationReport.java   |  3 +-
 .../ApplicationResourceUsageReport.java       | 29 +++++++++++++
 .../records/ApplicationSubmissionContext.java |  2 +-
 .../hadoop/yarn/api/records/Container.java    |  3 +-
 .../api/records/ContainerLaunchContext.java   | 19 +++++----
 .../yarn/api/records/NodeHealthStatus.java    |  2 -
 .../hadoop/yarn/api/records/Priority.java     | 13 ++++++
 .../hadoop/yarn/api/records/QueueInfo.java    |  2 +-
 .../distributedshell/ApplicationMaster.java   |  2 +-
 .../containermanager/AuxServices.java         |  2 +-
 28 files changed, 141 insertions(+), 36 deletions(-)

diff --git a/hadoop-mapreduce-project/CHANGES.txt b/hadoop-mapreduce-project/CHANGES.txt
index ccc5bb5177e..34252d94423 100644
--- a/hadoop-mapreduce-project/CHANGES.txt
+++ b/hadoop-mapreduce-project/CHANGES.txt
@@ -53,6 +53,9 @@ Release 0.23.1 - Unreleased
     MAPREDUCE-3411. Performance Upgrade for jQuery (Jonathan Eagles via 
     mahadev)
 
+    MAPREDUCE-3371. Review and improve the yarn-api javadocs. (Ravi Prakash
+    via mahadev)
+
   OPTIMIZATIONS
 
   BUG FIXES
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java
index d436f8e67fa..a0f220c2dcb 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java
@@ -91,8 +91,8 @@ public interface AMRMProtocol {
    * 
    * <p>This also doubles up as a <em>heartbeat</em> to let the 
    * <code>ResourceManager</code> know that the <code>ApplicationMaster</code>
-   * is alive. Thus, applications should use periodically make this call to 
-   * be kept alive.</p>
+   * is alive. Thus, applications should periodically make this call to be kept
+   * alive. The frequency depends on ??</p>
    * 
    * <p>The <code>ResourceManager</code> responds with list of allocated 
    * {@link Container}, status of completed containers and headroom information 
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java
index fb934591354..64b9cb64104 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java
@@ -68,7 +68,8 @@ public interface ClientRMProtocol {
    * {@link GetNewApplicationResponse}.</p>
    *
    * @param request request to get a new <code>ApplicationId</code>
-   * @return new <code>ApplicationId</code> to be used to submit an application
+   * @return response containing the new <code>ApplicationId</code> to be used
+   * to submit an application
    * @throws YarnRemoteException
    * @see #submitApplication(SubmitApplicationRequest)
    */
@@ -216,7 +217,7 @@ public interface ClientRMProtocol {
   
   /**
    * <p>The interface used by clients to get information about <em>queue 
-   * acls</em> for <em>current users</em> from the <code>ResourceManager</code>.
+   * acls</em> for <em>current user</em> from the <code>ResourceManager</code>.
    * </p>
    * 
    * <p>The <code>ResourceManager</code> responds with queue acls for all
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java
index 1d16cec26cd..0bb559a9fc5 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java
@@ -79,7 +79,7 @@ public interface ContainerManager {
    * to <em>stop</em> a {@link Container} allocated to it using this interface.
    * </p>
    * 
-   * <p>The <code>ApplicationMaster</code></p> sends a 
+   * <p>The <code>ApplicationMaster</code> sends a
    * {@link StopContainerRequest} which includes the {@link ContainerId} of the
    * container to be stopped.</p>
    * 
@@ -105,8 +105,8 @@ public interface ContainerManager {
    * current status of a <code>Container</code> from the 
    * <code>NodeManager</code>.</p>
    * 
-   * <p>The <code>ApplicationMaster</code></p> sends a 
-   * {@link GetContainerStatusRequest} which includes the {@link ContainerId} of 
+   * <p>The <code>ApplicationMaster</code> sends a
+   * {@link GetContainerStatusRequest} which includes the {@link ContainerId} of
    * the container whose status is needed.</p>
    *
    *<p>The <code>NodeManager</code> responds with 
@@ -115,7 +115,8 @@ public interface ContainerManager {
    *
    * @param request request to get <code>ContainerStatus</code> of a container
    *                with the specified <code>ContainerId</code>
-   * @return <code>ContainerStatus</code> of the container
+   * @return response containing the <code>ContainerStatus</code> of the
+   * container
    * @throws YarnRemoteException
    */
   @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java
index ff03dfea9e0..b3727a3f5c4 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java
@@ -50,7 +50,6 @@ import org.apache.hadoop.yarn.api.records.ResourceRequest;
  *     <li>
  *       A list of unused {@link Container} which are being returned. 
  *     </li>
- *     <li></li>
  *   </ul>
  * </p>
  * 
@@ -81,7 +80,7 @@ public interface AllocateRequest {
   void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
 
   /**
-   * Get the <em>response id</em>.
+   * Get the <em>response id</em> used to track duplicate responses.
    * @return <em>response id</em>
    */
   @Public
@@ -89,7 +88,7 @@ public interface AllocateRequest {
   int getResponseId();
 
   /**
-   * Set the <em>response id</em>
+   * Set the <em>response id</em> used to track duplicate responses.
    * @param id <em>response id</em>
    */
   @Public
@@ -113,7 +112,7 @@ public interface AllocateRequest {
   void setProgress(float progress);
 
   /**
-   * Get the list of <code>ResourceRequest</code> to upate the 
+   * Get the list of <code>ResourceRequest</code> to update the 
    * <code>ResourceManager</code> about the application's resource requirements.
    * @return the list of <code>ResourceRequest</code>
    */
@@ -130,9 +129,9 @@ public interface AllocateRequest {
   int getAskCount();
   
   /**
-   * Add list of <code>ResourceRequest</code> to upate the 
+   * Add list of <code>ResourceRequest</code> to update the 
    * <code>ResourceManager</code> about the application's resource requirements.
-   * @param resourceRequest list of <code>ResourceRequest</code> to upate the 
+   * @param resourceRequest list of <code>ResourceRequest</code> to update the 
    *                        <code>ResourceManager</code> about the application's 
    *                        resource requirements
    */
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java
index cdf8382b013..267a252918c 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java
@@ -34,7 +34,7 @@ import org.apache.hadoop.yarn.api.records.Container;
  *   <ul>
  *     <li>Response ID to track duplicate responses.</li>
  *     <li>
- *       A reboot flag to let the <code>ApplicationMaster</code> that its 
+ *       A reboot flag to let the <code>ApplicationMaster</code> know that its 
  *       horribly out of sync and needs to reboot.</li>
  *     <li>A list of newly allocated {@link Container}.</li>
  *     <li>A list of completed {@link Container}.</li>
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetAllApplicationsRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetAllApplicationsRequest.java
index a958331244c..ff42c053e94 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetAllApplicationsRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetAllApplicationsRequest.java
@@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
  * <p>The request from clients to get a report of all Applications
  * in the cluster from the <code>ResourceManager</code>.</p>
  *
+ * <p>Currently, this is empty.</p>
+ * 
  * @see ClientRMProtocol#getAllApplications(GetAllApplicationsRequest)
  */
 @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterMetricsRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterMetricsRequest.java
index 81b93428036..e2c2ca48af8 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterMetricsRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterMetricsRequest.java
@@ -25,6 +25,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
 /**
  * <p>The request sent by clients to get cluster metrics from the 
  * <code>ResourceManager</code>.</p>
+ * 
+ * <p>Currently, this is empty.</p>
  *
  * @see ClientRMProtocol#getClusterMetrics(GetClusterMetricsRequest)
  */
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesRequest.java
index 35ab1693717..0bbbd280214 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesRequest.java
@@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
  * <p>The request from clients to get a report of all nodes
  * in the cluster from the <code>ResourceManager</code>.</p>
  *
+ * <p>Currently, this is empty.</p>
+ *
  * @see ClientRMProtocol#getClusterNodes(GetClusterNodesRequest) 
  */
 @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesResponse.java
index e9475fd8d2c..9acf9434647 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesResponse.java
@@ -29,7 +29,7 @@ import org.apache.hadoop.yarn.api.records.NodeReport;
 
 /**
  * <p>The response sent by the <code>ResourceManager</code> to a client
- * requesting an {@link NodeReport} for all nodes.</p>
+ * requesting a {@link NodeReport} for all nodes.</p>
  * 
  * <p>The <code>NodeReport</code> contains per-node information such as 
  * available resources, number of containers, tracking url, rack name, health
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java
index 03b361d8377..48ba6515261 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java
@@ -27,7 +27,7 @@ import org.apache.hadoop.yarn.api.records.ContainerStatus;
 
 /**
  * <p>The response sent by the <code>NodeManager</code> to the 
- * <code>ApplicationMaster</code> when asked to obtainer <em>status</em> 
+ * <code>ApplicationMaster</code> when asked to obtain the <em>status</em> 
  * of a container.</p>
  * 
  * @see ContainerManager#getContainerStatus(GetContainerStatusRequest)
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationRequest.java
index a70989f1aab..20d2d81194e 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationRequest.java
@@ -27,6 +27,8 @@ import org.apache.hadoop.yarn.api.records.ApplicationId;
  * <p>The request sent by clients to get a new {@link ApplicationId} for
  * submitting an application.</p>
  * 
+ * <p>Currently, this is empty.</p>
+ * 
  * @see ClientRMProtocol#getNewApplication(GetNewApplicationRequest)
  */
 @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationResponse.java
index 4e7a7e565be..8da80e0afd6 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationResponse.java
@@ -28,7 +28,7 @@ import org.apache.hadoop.yarn.api.records.Resource;
 
 /**
  * <p>The response sent by the <code>ResourceManager</code> to the client for 
- * a request to a new {@link ApplicationId} for submitting applications.</p>
+ * a request to get a new {@link ApplicationId} for submitting applications.</p>
  * 
  * @see ClientRMProtocol#getNewApplication(GetNewApplicationRequest)
  */
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueUserAclsInfoRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueUserAclsInfoRequest.java
index ec16c1cb11e..7a18094fa95 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueUserAclsInfoRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueUserAclsInfoRequest.java
@@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
  * <p>The request sent by clients to the <code>ResourceManager</code> to 
  * get queue acls for the <em>current user</em>.</p>
  *
+ * <p>Currently, this is empty.</p>
+ * 
  * @see ClientRMProtocol#getQueueUserAcls(GetQueueUserAclsInfoRequest)
  */
 @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java
index a83c520a7c2..b14715bbd6b 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java
@@ -35,11 +35,53 @@ import org.apache.hadoop.yarn.api.ContainerManager;
 @Public
 @Stable
 public interface StartContainerResponse {
+  /**
+   * <p>Get the responses from all auxiliary services running on the 
+   * <code>NodeManager</code>.</p>
+   * <p>The responses are returned as a Map between the auxiliary service names
+   * and their corresponding opaque blob <code>ByteBuffer</code>s</p> 
+   * @return a Map between the auxiliary service names and their outputs
+   */
   Map<String, ByteBuffer> getAllServiceResponse();
+
+  /**
+   * Get the response from a single auxiliary service running on the
+   * <code>NodeManager</code>
+   * 
+   * @param key The auxiliary service name whose response is desired.
+   * @return The opaque blob <code>ByteBuffer</code> returned by the auxiliary
+   * service.
+   */
   ByteBuffer getServiceResponse(String key);
 
+  /**
+   * Add to the list of auxiliary services which have been started on the
+   * <code>NodeManager</code>. This is done only once when the
+   * <code>NodeManager</code> starts up
+   * @param serviceResponse A map from auxiliary service names to the opaque
+   * blob <code>ByteBuffer</code>s for that auxiliary service
+   */
   void addAllServiceResponse(Map<String, ByteBuffer> serviceResponse);
+
+  /**
+   * Add to the list of auxiliary services which have been started on the
+   * <code>NodeManager</code>. This is done only once when the
+   * <code>NodeManager</code> starts up
+   * 
+   * @param key The auxiliary service name
+   * @param value The opaque blob <code>ByteBuffer</code> managed by the
+   * auxiliary service
+   */
   void setServiceResponse(String key, ByteBuffer value);
+
+  /**
+   * Remove a single auxiliary service from the StartContainerResponse object
+   * @param key The auxiliary service to remove
+   */
   void removeServiceResponse(String key);
+  
+  /**
+   * Remove all the auxiliary services from the StartContainerResponse object
+   */
   void clearServiceResponse();
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java
index 6bfd7cffe86..c94e6987423 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java
@@ -27,6 +27,8 @@ import org.apache.hadoop.yarn.api.ContainerManager;
  * <code>ApplicationMaster</code> when asked to <em>stop</em> an
  * allocated container.</p>
  * 
+ * <p>Currently, this is empty.</p>
+ * 
  * @see ContainerManager#stopContainer(StopContainerRequest)
  */
 @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/SubmitApplicationResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/SubmitApplicationResponse.java
index 618641be6ae..7acd24c87d7 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/SubmitApplicationResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/SubmitApplicationResponse.java
@@ -26,6 +26,8 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
  * <p>The response sent by the <code>ResourceManager</code> to a client on
  * application submission.</p>
  * 
+ * <p>Currently, this is empty.</p>
+ * 
  * @see ClientRMProtocol#submitApplication(SubmitApplicationRequest)
  */
 @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java
index e009d2eb17d..8963d4a5bcf 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java
@@ -35,7 +35,7 @@ import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest;
  *   <ul>
  *     <li>Response ID to track duplicate responses.</li>
  *     <li>
- *       A reboot flag to let the <code>ApplicationMaster</code> that its 
+ *       A reboot flag to let the <code>ApplicationMaster</code> know that its 
  *       horribly out of sync and needs to reboot.</li>
  *     <li>A list of newly allocated {@link Container}.</li>
  *     <li>A list of completed {@link Container}.</li>
@@ -100,7 +100,7 @@ public interface AMResponse {
   /**
    * Get the <em>available headroom</em> for resources in the cluster for the 
    * application.
-   * @return limit available headroom for resources in the cluster for the 
+   * @return limit of available headroom for resources in the cluster for the 
    * application
    */
   @Public
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationReport.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationReport.java
index cc8b6d46731..11740e849ad 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationReport.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationReport.java
@@ -33,7 +33,7 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
  *     <li>Applications user.</li>
  *     <li>Application queue.</li>
  *     <li>Application name.</li>
- *     <li>Host on which the <code>ApplicationMaster</code>is running.</li>
+ *     <li>Host on which the <code>ApplicationMaster</code> is running.</li>
  *     <li>RPC port of the <code>ApplicationMaster</code>.</li>
  *     <li>Tracking URL.</li>
  *     <li>{@link YarnApplicationState} of the application.</li>
@@ -215,6 +215,7 @@ public interface ApplicationReport {
 
   /**
    * Get the <em>final finish status</em> of the application.
+   * @return <em>final finish status</em> of the application
    */
   @Public
   @Stable
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationResourceUsageReport.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationResourceUsageReport.java
index 3fd0d39d6d3..9d45e8b75f4 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationResourceUsageReport.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationResourceUsageReport.java
@@ -33,22 +33,43 @@ import org.apache.hadoop.classification.InterfaceStability.Unstable;
 @Public
 @Stable
 public interface ApplicationResourceUsageReport {
+
+  /**
+   * Get the number of used containers
+   * @return the number of used containers
+   */
   @Public
   @Stable
   int getNumUsedContainers();
 
+  /**
+   * Set the number of used containers
+   * @param num_containers the number of used containers
+   */
   @Private
   @Unstable
   void setNumUsedContainers(int num_containers);
 
+  /**
+   * Get the number of reserved containers
+   * @return the number of reserved containers
+   */
   @Public
   @Stable
   int getNumReservedContainers();
 
+  /**
+   * Set the number of reserved containers
+   * @param num_reserved_containers the number of reserved containers
+   */
   @Private
   @Unstable
   void setNumReservedContainers(int num_reserved_containers);
 
+  /**
+   * Get the used <code>Resource</code>
+   * @return the used <code>Resource</code>
+   */
   @Public
   @Stable
   Resource getUsedResources();
@@ -57,6 +78,10 @@ public interface ApplicationResourceUsageReport {
   @Unstable
   void setUsedResources(Resource resources);
 
+  /**
+   * Get the reserved <code>Resource</code>
+   * @return the reserved <code>Resource</code>
+   */
   @Public
   @Stable
   Resource getReservedResources();
@@ -65,6 +90,10 @@ public interface ApplicationResourceUsageReport {
   @Unstable
   void setReservedResources(Resource reserved_resources);
 
+  /**
+   * Get the needed <code>Resource</code>
+   * @return the needed <code>Resource</code>
+   */
   @Public
   @Stable
   Resource getNeededResources();
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationSubmissionContext.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationSubmissionContext.java
index 5ef71fea94d..67e76019711 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationSubmissionContext.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationSubmissionContext.java
@@ -26,7 +26,7 @@ import org.apache.hadoop.classification.InterfaceStability.Unstable;
 import org.apache.hadoop.yarn.api.ClientRMProtocol;
 
 /**
- * <p><code>ApplicationSubmissionContext</code> represents the all of the 
+ * <p><code>ApplicationSubmissionContext</code> represents all of the
  * information needed by the <code>ResourceManager</code> to launch 
  * the <code>ApplicationMaster</code> for an application.</p>
  * 
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Container.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Container.java
index ff054b22ac5..4ac8e0748c9 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Container.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Container.java
@@ -38,8 +38,7 @@ import org.apache.hadoop.yarn.api.ContainerManager;
  *   <ul>
  *     <li>{@link ContainerId} for the container, which is globally unique.</li>
  *     <li>
- *       {@link NodeId} of the node on which identifies the node on which it
- *       is allocated.
+ *       {@link NodeId} of the node on which it is allocated.
  *     </li>
  *     <li>HTTP uri of the node.</li>
  *     <li>{@link Resource} allocated to the container.</li>
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java
index 459476dd290..78f85b2b0ec 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java
@@ -27,7 +27,7 @@ import org.apache.hadoop.classification.InterfaceStability.Stable;
 import org.apache.hadoop.yarn.api.ContainerManager;
 
 /**
- * <p><code>ContainerLaunchContext</code> represents the all of the information
+ * <p><code>ContainerLaunchContext</code> represents all of the information
  * needed by the <code>NodeManager</code> to launch a container.</p>
  * 
  * <p>It includes details such as:
@@ -127,7 +127,8 @@ public interface ContainerLaunchContext {
   Map<String, LocalResource> getLocalResources();
   
   /**
-   * Set <code>LocalResource</code> required by the container.
+   * Set <code>LocalResource</code> required by the container. All pre-existing
+   * Map entries are cleared before adding the new Map
    * @param localResources <code>LocalResource</code> required by the container
    */
   @Public
@@ -143,7 +144,8 @@ public interface ContainerLaunchContext {
   Map<String, ByteBuffer> getServiceData();
   
   /**
-   * Set application-specific binary <em>service data</em>.
+   * Set application-specific binary <em>service data</em>. All pre-existing Map
+   * entries are preserved.
    * @param serviceData application-specific binary <em>service data</em>
    */
   @Public
@@ -159,7 +161,8 @@ public interface ContainerLaunchContext {
   Map<String, String> getEnvironment();
     
   /**
-   * Add <em>environment variables</em> for the container.
+   * Add <em>environment variables</em> for the container. All pre-existing Map
+   * entries are cleared before adding the new Map
    * @param environment <em>environment variables</em> for the container
    */
   @Public
@@ -175,7 +178,8 @@ public interface ContainerLaunchContext {
   List<String> getCommands();
   
   /**
-   * Add the list of <em>commands</em> for launching the container.
+   * Add the list of <em>commands</em> for launching the container. All
+   * pre-existing List entries are cleared before adding the new List
    * @param commands the list of <em>commands</em> for launching the container
    */
   @Public
@@ -191,8 +195,9 @@ public interface ContainerLaunchContext {
   public Map<ApplicationAccessType, String> getApplicationACLs();
 
   /**
-   * Set the <code>ApplicationACL</code>s for the application. 
-   * @param acls
+   * Set the <code>ApplicationACL</code>s for the application. All pre-existing
+   * Map entries are cleared before adding the new Map
+   * @param acls <code>ApplicationACL</code>s for the application
    */
   @Public
   @Stable
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/NodeHealthStatus.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/NodeHealthStatus.java
index c507e45b1a4..eca22fa4297 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/NodeHealthStatus.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/NodeHealthStatus.java
@@ -35,8 +35,6 @@ import org.apache.hadoop.yarn.api.ClientRMProtocol;
  *     </li>
  *     <li>The previous time at which the health status was reported.</li>
  *     <li>A diagnostic report on the health status.</li>
- *     <li></li>
- *     <li></li>
  *   </ul>
  * </p>
  * 
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Priority.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Priority.java
index bcc72a2888a..bed0788365e 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Priority.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/Priority.java
@@ -18,10 +18,23 @@
 
 package org.apache.hadoop.yarn.api.records;
 
+/**
+ * The priority assigned to a ResourceRequest or Application or Container 
+ * allocation 
+ *
+ */
 public interface Priority extends Comparable<Priority> {
   
+  /**
+   * Get the assigned priority
+   * @return the assigned priority
+   */
   public abstract int getPriority();
   
+  /**
+   * Set the assigned priority
+   * @param priority the assigned priority
+   */
   public abstract void setPriority(int priority);
   
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueInfo.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueInfo.java
index a783c3ced8a..b4b45c44364 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueInfo.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueInfo.java
@@ -27,7 +27,7 @@ import org.apache.hadoop.classification.InterfaceStability.Unstable;
 import org.apache.hadoop.yarn.api.ClientRMProtocol;
 
 /**
- * <p>QueueInfo</p> is a report of the runtime information of the queue.</p>
+ * <p>QueueInfo is a report of the runtime information of the queue.</p>
  * 
  * <p>It includes information such as:
  *   <ul>
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-applications/hadoop-yarn-applications-distributedshell/src/main/java/org/apache/hadoop/yarn/applications/distributedshell/ApplicationMaster.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-applications/hadoop-yarn-applications-distributedshell/src/main/java/org/apache/hadoop/yarn/applications/distributedshell/ApplicationMaster.java
index ed8303c0645..ab371f51fe4 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-applications/hadoop-yarn-applications-distributedshell/src/main/java/org/apache/hadoop/yarn/applications/distributedshell/ApplicationMaster.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-applications/hadoop-yarn-applications-distributedshell/src/main/java/org/apache/hadoop/yarn/applications/distributedshell/ApplicationMaster.java
@@ -93,7 +93,7 @@ import org.apache.hadoop.yarn.util.Records;
  * to inform the <code>ResourceManager</code> that it is up and alive. The {@link AMRMProtocol#allocate} to the 
  * <code>ResourceManager</code> from the <code>ApplicationMaster</code> acts as a heartbeat.
  * 
- * <p> For the actual handling of the job, the <code>ApplicationMaster</code> has to request for the 
+ * <p> For the actual handling of the job, the <code>ApplicationMaster</code> has to request the 
  * <code>ResourceManager</code> via {@link AllocateRequest} for the required no. of containers using {@link ResourceRequest}
  * with the necessary resource specifications such as node location, computational (memory/disk/cpu) resource requirements.
  * The <code>ResourceManager</code> responds with an {@link AllocateResponse} that informs the <code>ApplicationMaster</code> 
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/AuxServices.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/AuxServices.java
index 4b6e8a62493..83676e57edf 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/AuxServices.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-server/hadoop-yarn-server-nodemanager/src/main/java/org/apache/hadoop/yarn/server/nodemanager/containermanager/AuxServices.java
@@ -68,7 +68,7 @@ public class AuxServices extends AbstractService
   /**
    * @return the meta data for all registered services, that have been started.
    * If a service has not been started no metadata will be available. The key
-   * the the name of the service as defined in the configuration.
+   * is the name of the service as defined in the configuration.
    */
   public Map<String, ByteBuffer> getMeta() {
     Map<String, ByteBuffer> metaClone = new HashMap<String, ByteBuffer>(