Merge -r 1163068:1163069 from trunk to branch-0.23 to fix MAPREDUCE-2897.

git-svn-id: https://svn.apache.org/repos/asf/hadoop/common/branches/branch-0.23@1163070 13f79535-47bb-0310-9956-ffa450edef68

hadoop-mapreduce-project/CHANGES.txt

@@ -1170,6 +1170,9 @@ Release 0.23.0 - Unreleased
 
     MAPREDUCE-2886. Fix Javadoc warnings in MapReduce. (mahadev)
 
+    MAPREDUCE-2897. Javadoc for ClientRMProtocol protocol and related records. 
+    (acmurthy)
+
 Release 0.22.0 - Unreleased
 
   INCOMPATIBLE CHANGES

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java

@@ -89,6 +89,11 @@ public interface AMRMProtocol {
    * of {@link ResourceRequest} and returns unused {@link Container} allocated 
    * to it via {@link AllocateRequest}.</p>
    * 
+   * <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>
+   * 
    * <p>The <code>ResourceManager</code> responds with list of allocated 
    * {@link Container}, status of completed containers and headroom information 
    * for the application.</p> 

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java

@@ -18,6 +18,9 @@
 
 package org.apache.hadoop.yarn.api;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+
 import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationRequest;
 import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationResponse;
 import org.apache.hadoop.yarn.api.protocolrecords.GetAllApplicationsRequest;
@@ -36,17 +39,190 @@ import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest;
 import org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoResponse;
 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest;
 import org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationResponse;
+import org.apache.hadoop.yarn.api.records.ApplicationId;
+import org.apache.hadoop.yarn.api.records.ApplicationReport;
+import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
+import org.apache.hadoop.yarn.api.records.NodeReport;
+import org.apache.hadoop.yarn.api.records.Resource;
+import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
 import org.apache.hadoop.yarn.exceptions.YarnRemoteException;
 
+/**
+ * <p>The protocol between clients and the <code>ResourceManager</code>
+ * to submit/abort jobs and to get information on applications, cluster metrics,
+ * nodes, queues and ACLs.</p> 
+ */
+@Public
+@Stable
 public interface ClientRMProtocol {
-  public GetNewApplicationIdResponse getNewApplicationId(GetNewApplicationIdRequest request) throws YarnRemoteException;
+  /**
-  public SubmitApplicationResponse submitApplication(SubmitApplicationRequest request) throws YarnRemoteException;
+   * <p>The interface used by clients to obtain a new {@link ApplicationId} for 
-  public FinishApplicationResponse finishApplication(FinishApplicationRequest request) throws YarnRemoteException;
+   * submitting new applications.</p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with a new, monotonically
+   * increasing, {@link ApplicationId} which is used by the client to submit
+   * a new application.</p>
+   * 
+   * @param request request to get a new <code>ApplicationId</code>
+   * @return new <code>ApplicationId</code> to be used to submit an application
+   * @throws YarnRemoteException
+   * @see #submitApplication(SubmitApplicationRequest)
+   */
+  public GetNewApplicationIdResponse getNewApplicationId(
+      GetNewApplicationIdRequest request) 
+  throws YarnRemoteException;
   
-  public GetApplicationReportResponse getApplicationReport(GetApplicationReportRequest request) throws YarnRemoteException;
+  /**
-  public GetClusterMetricsResponse getClusterMetrics(GetClusterMetricsRequest request) throws YarnRemoteException;
+   * <p>The interface used by clients to submit a new application to the
-  public GetAllApplicationsResponse getAllApplications(GetAllApplicationsRequest request) throws YarnRemoteException;
+   * <code>ResourceManager.</code></p>
-  public GetClusterNodesResponse getClusterNodes(GetClusterNodesRequest request) throws YarnRemoteException;
+   * 
-  public GetQueueInfoResponse getQueueInfo(GetQueueInfoRequest request) throws YarnRemoteException;
+   * <p>The client is required to provide details such as queue, 
-  public GetQueueUserAclsInfoResponse getQueueUserAcls(GetQueueUserAclsInfoRequest request) throws YarnRemoteException;
+   * {@link Resource} required to run the <code>ApplicationMaster</code>, 
+   * the equivalent of {@link ContainerLaunchContext} for launching
+   * the <code>ApplicationMaster</code> etc. via the 
+   * {@link SubmitApplicationRequest}.</p>
+   * 
+   * <p>Currently the <code>ResourceManager</code> sends an immediate (empty) 
+   * {@link SubmitApplicationResponse} on accepting the submission and throws 
+   * an exception if it rejects the submission.</p>
+   * 
+   * <p> In secure mode,the <code>ResourceManager</code> verifies access to
+   * queues etc. before accepting the application submission.</p>
+   * 
+   * @param request request to submit a new application
+   * @return (empty) response on accepting the submission
+   * @throws YarnRemoteException
+   * @see #getNewApplicationId(GetNewApplicationIdRequest)
+   */
+  public SubmitApplicationResponse submitApplication(
+      SubmitApplicationRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by clients to request the 
+   * <code>ResourceManager</code> to abort submitted application.</p>
+   * 
+   * <p>The client, via {@link FinishApplicationRequest} provides the
+   * {@link ApplicationId} of the application to be aborted.</p>
+   * 
+   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
+   * application, queue etc. before terminating the application.</p> 
+   * 
+   * <p>Currently, the <code>ResourceManager</code> returns an empty response
+   * on success and throws an exception on rejecting the request.</p>
+   * 
+   * @param request request to abort a submited application
+   * @return <code>ResourceManager</code> returns an empty response
+   *         on success and throws an exception on rejecting the request
+   * @throws YarnRemoteException
+   * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 
+   */
+  public FinishApplicationResponse finishApplication(
+      FinishApplicationRequest request) 
+  throws YarnRemoteException;
+
+  /**
+   * <p>The interface used by clients to get a report of an Application from
+   * the <code>ResourceManager</code>.</p>
+   * 
+   * <p>The client, via {@link GetApplicationReportRequest} provides the
+   * {@link ApplicationId} of the application.</p>
+   *
+   * <p> In secure mode,the <code>ResourceManager</code> verifies access to the
+   * application, queue etc. before accepting the request.</p> 
+   * 
+   * <p>The <code>ResourceManager</code> responds with a 
+   * {@link GetApplicationReportResponse} which includes the 
+   * {@link ApplicationReport} for the application.</p>
+   * 
+   * @param request request for an application report
+   * @return application report 
+   * @throws YarnRemoteException
+   */
+  public GetApplicationReportResponse getApplicationReport(
+      GetApplicationReportRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by clients to get metrics about the cluster from
+   * the <code>ResourceManager</code>.</p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with a
+   * {@link GetClusterMetricsResponse} which includes the 
+   * {@link YarnClusterMetrics} with details such as number of current
+   * nodes in the cluster.</p>
+   * 
+   * @param request request for cluster metrics
+   * @return cluster metrics
+   * @throws YarnRemoteException
+   */
+  public GetClusterMetricsResponse getClusterMetrics(
+      GetClusterMetricsRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by clients to get a report of all Applications
+   * in the cluster from the <code>ResourceManager</code>.</p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with a 
+   * {@link GetAllApplicationsResponse} which includes the 
+   * {@link ApplicationReport} for all the applications.</p>
+   * 
+   * @param request request for report on all running applications
+   * @return report on all running applications
+   * @throws YarnRemoteException
+   */
+  public GetAllApplicationsResponse getAllApplications(
+      GetAllApplicationsRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by clients to get a report of all nodes
+   * in the cluster from the <code>ResourceManager</code>.</p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with a 
+   * {@link GetClusterNodesResponse} which includes the 
+   * {@link NodeReport} for all the nodes in the cluster.</p>
+   * 
+   * @param request request for report on all nodes
+   * @return report on all nodes
+   * @throws YarnRemoteException
+   */
+  public GetClusterNodesResponse getClusterNodes(
+      GetClusterNodesRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by clients to get information about <em>queues</em>
+   * from the <code>ResourceManager</code>.</p>
+   * 
+   * <p>The client, via {@link GetQueueInfoRequest}, can ask for details such
+   * as used/total resources, child queues, running applications etc.</p>
+   *
+   * <p> In secure mode,the <code>ResourceManager</code> verifies access before
+   * providing the information.</p> 
+   * 
+   * @param request request to get queue information
+   * @return queue information
+   * @throws YarnRemoteException
+   */
+  public GetQueueInfoResponse getQueueInfo(
+      GetQueueInfoRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by clients to get information about <em>queue 
+   * acls</em> for <em>current users</em> from the <code>ResourceManager</code>.
+   * </p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with queue acls for all
+   * existing queues.</p>
+   * 
+   * @param request request to get queue acls for <em>current user</em>
+   * @return queue acls for <em>current user</em>
+   * @throws YarnRemoteException
+   */
+  public GetQueueUserAclsInfoResponse getQueueUserAcls(
+      GetQueueUserAclsInfoRequest request) 
+  throws YarnRemoteException;
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ContainerManager.java

@@ -115,7 +115,7 @@ public interface ContainerManager {
    *
    * @param request request to get <code>ContainerStatus</code> of a container
    *                with the specified <code>ContainerId</code>
-   * @return the <code>ContainerStatus</code> of the container
+   * @return <code>ContainerStatus</code> of the container
    * @throws YarnRemoteException
    */
   @Public

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java

@@ -32,8 +32,7 @@ import org.apache.hadoop.yarn.api.records.ResourceRequest;
 
 /**
  * <p>The core request sent by the <code>ApplicationMaster</code> to the 
- * <code>ResourceManager</code> to obtain resources in the cluster via
+ * <code>ResourceManager</code> to obtain resources in the cluster.</p> 
- * {@link AMRMProtocol#allocate(AllocateRequest)}.</p> 
  *
  * <p>The request includes:
  *   <ul>
@@ -55,13 +54,14 @@ import org.apache.hadoop.yarn.api.records.ResourceRequest;
  *   </ul>
  * </p>
  * 
+ * @see AMRMProtocol#allocate(AllocateRequest)
  */
 @Public
 @Stable
 public interface AllocateRequest {
 
   /**
-   * Get the {@link ApplicationAttemptId} being managed by the 
+   * Get the <code>ApplicationAttemptId</code> being managed by the 
    * <code>ApplicationMaster</code>.
    * @return <code>ApplicationAttemptId</code> being managed by the 
    *         <code>ApplicationMaster</code>
@@ -70,32 +70,46 @@ public interface AllocateRequest {
   @Stable
   ApplicationAttemptId getApplicationAttemptId();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <code>ApplicationAttemptId</code> being managed by the 
+   * <code>ApplicationMaster</code>.
+   * @param applicationAttemptId <code>ApplicationAttemptId</code> being managed 
+   *                             by the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
 
   /**
-   * Get the response id.
+   * Get the <em>response id</em>.
-   * @return the response id
+   * @return <em>response id</em>
    */
   @Public
   @Stable
   int getResponseId();
 
-  @Private
+  /**
-  @Unstable
+   * Set the <em>response id</em>
+   * @param id <em>response id</em>
+   */
+  @Public
+  @Stable
   void setResponseId(int id);
 
   /**
-   * Get the current progress of application. 
+   * Get the <em>current progress</em> of application. 
-   * @return the current progress of application
+   * @return <em>current progress</em> of application
    */
   @Public
   @Stable
   float getProgress();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <em>current progress</em> of application
+   * @param progress <em>current progress</em> of application
+   */
+  @Public
+  @Stable
   void setProgress(float progress);
 
   /**
@@ -115,6 +129,29 @@ public interface AllocateRequest {
   @Unstable
   int getAskCount();
   
+  /**
+   * Add list of <code>ResourceRequest</code> to upate the 
+   * <code>ResourceManager</code> about the application's resource requirements.
+   * @param resourceRequest list of <code>ResourceRequest</code> to upate the 
+   *                        <code>ResourceManager</code> about the application's 
+   *                        resource requirements
+   */
+  @Public
+  @Stable
+  void addAllAsks(List<ResourceRequest> resourceRequest);
+
+  @Private
+  @Unstable
+  void addAsk(ResourceRequest request);
+
+  @Private
+  @Unstable
+  void removeAsk(int index);
+
+  @Private
+  @Unstable
+  void clearAsks();
+
   /**
    * Get the list of <code>ContainerId</code> of unused containers being 
    * released by the <code>ApplicationMaster</code>.
@@ -133,26 +170,15 @@ public interface AllocateRequest {
   @Unstable
   int getReleaseCount();
 
-  
+  /**
-  @Private
+   * Add the list of <code>ContainerId</code> of unused containers being 
-  @Unstable
+   * released by the <code>ApplicationMaster</code>
-  void addAllAsks(List<ResourceRequest> resourceRequest);
+   * @param releaseContainers list of <code>ContainerId</code> of unused 
-  
+   *                          containers being released by the <
-  @Private
+   *                          code>ApplicationMaster</code>
-  @Unstable
+   */
-  void addAsk(ResourceRequest request);
+  @Public
-  
+  @Stable
-  @Private
-  @Unstable
-  void removeAsk(int index);
-  
-  @Private
-  @Unstable
-  void clearAsks();
-  
-  
-  @Private
-  @Unstable
   void addAllReleases(List<ContainerId> releaseContainers);
   
   @Private

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java

@@ -28,8 +28,7 @@ import org.apache.hadoop.yarn.api.records.Container;
 
 /**
  * <p>The response sent by the <code>ResourceManager</code> the  
- * <code>ApplicationMaster</code> during resource negotiation via
+ * <code>ApplicationMaster</code> during resource negotiation.</p>
- * {@link AMRMProtocol#allocate(AllocateRequest)}.</p>
  *
  * <p>The response, via {@link AMResponse}, includes:
  *   <ul>
@@ -45,6 +44,8 @@ import org.apache.hadoop.yarn.api.records.Container;
  *     </li>
  *   </ul>
  * </p>
+ * 
+ * @see AMRMProtocol#allocate(AllocateRequest)
  */
 @Public
 @Stable

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterRequest.java

@@ -18,18 +18,14 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
-import org.apache.hadoop.classification.InterfaceAudience.Private;
 import org.apache.hadoop.classification.InterfaceAudience.Public;
 import org.apache.hadoop.classification.InterfaceStability.Stable;
-import org.apache.hadoop.classification.InterfaceStability.Unstable;
 import org.apache.hadoop.yarn.api.AMRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
 
 /**
  * <p>The finalization request sent by the <code>ApplicationMaster</code> to 
- * inform the <code>ResourceManager</code> about its completion via the
+ * inform the <code>ResourceManager</code> about its completion.</p>
- * {@link AMRMProtocol#finishApplicationMaster(FinishApplicationMasterRequest)}
- * api.</p>
  * 
  * <p>The final request includes details such:
  *   <ul>
@@ -46,11 +42,12 @@ import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
  *   </ul>
  * </p>
  *
+ * @see AMRMProtocol#finishApplicationMaster(FinishApplicationMasterRequest)
  */
 public interface FinishApplicationMasterRequest {
 
   /**
-   * Get the {@link ApplicationAttemptId} being managed by the 
+   * Get the <code>ApplicationAttemptId</code> being managed by the 
    * <code>ApplicationMaster</code>.
    * @return <code>ApplicationAttemptId</code> being managed by the 
    *         <code>ApplicationMaster</code>
@@ -59,44 +56,63 @@ public interface FinishApplicationMasterRequest {
   @Stable
   ApplicationAttemptId getApplicationAttemptId();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <code>ApplicationAttemptId</code> being managed by the 
+   * <code>ApplicationMaster</code>.
+   * @param applicationAttemptId <code>ApplicationAttemptId</code> being managed 
+   *                             by the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   void setAppAttemptId(ApplicationAttemptId applicationAttemptId);
 
   /**
-   * Get final state of the <code>ApplicationMaster</code>.
+   * Get <em>final state</em> of the <code>ApplicationMaster</code>.
-   * @return final state of the <code>ApplicationMaster</code>
+   * @return <em>final state</em> of the <code>ApplicationMaster</code>
    */
   @Public
   @Stable
   String getFinalState();
   
-  @Private
+  /**
-  @Unstable
+   * Set <em>final state</em> of the <code>ApplicationMaster</code>
-  void setFinalState(String string);
+   * @param finalState <em>final state</em> of the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  void setFinalState(String finalState);
 
   /**
-   * Get diagnostic information if the application failed.
+   * Get <em>diagnostic information</em> on application failure.
-   * @return diagnostic information if the application failed
+   * @return <em>diagnostic information</em> on application failure
    */
   @Public
   @Stable
   String getDiagnostics();
   
-  @Private
+  /**
-  @Unstable
+   * Set <em>diagnostic information</em> on application failure.
-  void setDiagnostics(String string);
+   * @param diagnostics <em>diagnostic information</em> on application failure
+   */
+  @Public
+  @Stable
+  void setDiagnostics(String diagnostics);
 
   /**
-   * Get the tracking URL for the <code>ApplicationMaster</code>.
+   * Get the <em>tracking URL</em> for the <code>ApplicationMaster</code>.
-   * @return the tracking URL for the <code>ApplicationMaster</code>
+   * @return <em>tracking URL</em>for the <code>ApplicationMaster</code>
    */
   @Public
   @Stable
   String getTrackingUrl();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <em>tracking URL</em>for the <code>ApplicationMaster</code>
-  void setTrackingUrl(String historyUrl);
+   * @param url <em>tracking URL</em>for the 
+   *                   <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  void setTrackingUrl(String url);
 
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterResponse.java

@@ -24,11 +24,11 @@ import org.apache.hadoop.yarn.api.AMRMProtocol;
 
 /**
  * <p>The response sent by the <code>ResourceManager</code> to a 
- * <code>ApplicationMaster</code> on it's completion via the
+ * <code>ApplicationMaster</code> on it's completion.</p>
- * {@link AMRMProtocol#finishApplicationMaster(FinishApplicationMasterRequest)}
- * api.</p>
  * 
  * <p>Currently, this is empty.</p>
+ * 
+ * @see AMRMProtocol#finishApplicationMaster(FinishApplicationMasterRequest)
  */
 @Public
 @Stable

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationRequest.java

@@ -18,10 +18,34 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationId;
 
+/**
+ * <p>The request sent by the client to the <code>ResourceManager</code>
+ * to abort a submitted application.</p>
+ * 
+ * <p>The request includes the {@link ApplicationId} of the application to be
+ * aborted.</p>
+ * 
+ * @see ClientRMProtocol#finishApplication(FinishApplicationRequest)
+ */
+@Public
+@Stable
 public interface FinishApplicationRequest {
+  /**
+   * Get the <code>ApplicationId</code> of the application to be aborted.
+   * @return <code>ApplicationId</code> of the application to be aborted
+   */
+  @Public
+  @Stable
   public abstract ApplicationId getApplicationId();
   
+  @Private
+  @Unstable
   public abstract void setApplicationId(ApplicationId applicationId);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationResponse.java

@@ -18,6 +18,20 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to the client
+ * aborting a submitted application.</p>
+ *
+ * <p>Currently it's empty.</p>
+ * 
+ * @see ClientRMProtocol#finishApplication(FinishApplicationRequest)
+ */
+@Public
+@Stable
 public interface FinishApplicationResponse {
 
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetAllApplicationsRequest.java

@@ -18,5 +18,17 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+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>
+ *
+ * @see ClientRMProtocol#getAllApplications(GetAllApplicationsRequest)
+ */
+@Public
+@Stable
 public interface GetAllApplicationsRequest {
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetAllApplicationsResponse.java

@@ -20,9 +20,36 @@ package org.apache.hadoop.yarn.api.protocolrecords;
 
 import java.util.List;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationReport;
 
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to a client
+ * requesting an {@link ApplicationReport} for all applications.</p>
+ * 
+ * <p>The <code>ApplicationReport</code> for each application includes details 
+ * such as user, queue, name, host on which the <code>ApplicationMaster</code> 
+ * is running, RPC port, tracking URL, diagnostics, start time etc.</p>
+ * 
+ * @see ApplicationReport
+ * @see ClientRMProtocol#getAllApplications(GetAllApplicationsRequest)
+ */
+@Public
+@Stable
 public interface GetAllApplicationsResponse {
+  /**
+   * Get <code>ApplicationReport</code> for all applications.
+   * @return <code>ApplicationReport</code> for all applications
+   */
+  @Public
+  @Stable
   List<ApplicationReport> getApplicationList();
+  
+  @Private
+  @Unstable
   void setApplicationList(List<ApplicationReport> applications);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetApplicationReportRequest.java

@@ -18,9 +18,34 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationId;
+import org.apache.hadoop.yarn.api.records.ApplicationReport;
 
+/**
+ * <p>The request sent by a client to the <code>ResourceManager</code> to 
+ * get an {@link ApplicationReport} for an application.</p>
+ * 
+ * <p>The request should include the {@link ApplicationId} of the 
+ * application.</p>
+ * 
+ * @see ClientRMProtocol#getApplicationReport(GetApplicationReportRequest)
+ * @see ApplicationReport
+ */
+@Public
+@Stable
 public interface GetApplicationReportRequest {
-  public abstract ApplicationId getApplicationId();
+  /**
-  public abstract void setApplicationId(ApplicationId applicationId);
+   * Get the <code>ApplicationId</code> of the application.
+   * @return <code>ApplicationId</code> of the application
+   */
+  public ApplicationId getApplicationId();
+  
+  /**
+   * Set the <code>ApplicationId</code> of the application
+   * @param applicationId <code>ApplicationId</code> of the application
+   */
+  public void setApplicationId(ApplicationId applicationId);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetApplicationReportResponse.java

@@ -18,9 +18,35 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationReport;
 
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to a client
+ * requesting an application report.</p>
+ * 
+ * <p>The response includes an {@link ApplicationReport} which has details such 
+ * as user, queue, name, host on which the <code>ApplicationMaster</code> is 
+ * running, RPC port, tracking URL, diagnostics, start time etc.</p>
+ * 
+ * @see ClientRMProtocol#getApplicationReport(GetApplicationReportRequest)
+ */
+@Public
+@Stable
 public interface GetApplicationReportResponse {
-  public abstract ApplicationReport getApplicationReport();
+  /**
-  public abstract void setApplicationReport(ApplicationReport ApplicationReport);
+   * Get the <code>ApplicationReport</code> for the application.
+   * @return <code>ApplicationReport</code> for the application
+   */
+  @Public
+  @Stable
+  public ApplicationReport getApplicationReport();
+  
+  @Private
+  @Unstable
+  public void setApplicationReport(ApplicationReport ApplicationReport);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterMetricsRequest.java

@@ -18,6 +18,18 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p>The request sent by clients to get cluster metrics from the 
+ * <code>ResourceManager</code>.</p>
+ *
+ * @see ClientRMProtocol#getClusterMetrics(GetClusterMetricsRequest)
+ */
+@Public
+@Stable
 public interface GetClusterMetricsRequest {
 
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterMetricsResponse.java

@@ -18,9 +18,32 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.YarnClusterMetrics;
 
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to a client
+ * requesting cluster metrics.<p>
+ * 
+ * @see YarnClusterMetrics
+ * @see ClientRMProtocol#getClusterMetrics(GetClusterMetricsRequest)
+ */
+@Public
+@Stable
 public interface GetClusterMetricsResponse {
-  public abstract YarnClusterMetrics getClusterMetrics();
+  /**
-  public abstract void setClusterMetrics(YarnClusterMetrics metrics);
+   * Get the <code>YarnClusterMetrics</code> for the cluster.
+   * @return <code>YarnClusterMetrics</code> for the cluster
+   */
+  @Public
+  @Stable
+  public YarnClusterMetrics getClusterMetrics();
+  
+  @Private
+  @Unstable
+  public void setClusterMetrics(YarnClusterMetrics metrics);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesRequest.java

@@ -18,6 +18,18 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+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>
+ *
+ * @see ClientRMProtocol#getClusterNodes(GetClusterNodesRequest) 
+ */
+@Public
+@Stable
 public interface GetClusterNodesRequest {
 
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetClusterNodesResponse.java

@@ -20,9 +20,36 @@ package org.apache.hadoop.yarn.api.protocolrecords;
 
 import java.util.List;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 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>
+ * 
+ * <p>The <code>NodeReport</code> contains per-node information such as 
+ * available resources, number of containers, tracking url, rack name, health
+ * status etc.
+ * 
+ * @see NodeReport
+ * @see ClientRMProtocol#getClusterNodes(GetClusterNodesRequest)
+ */
+@Public
+@Stable
 public interface GetClusterNodesResponse {
+  /**
+   * Get <code>NodeReport</code> for all nodes in the cluster.
+   * @return <code>NodeReport</code> for all nodes in the cluster
+   */
+  @Public
+  @Stable
   List<NodeReport> getNodeReports();
+  
+  @Private
+  @Unstable
   void setNodeReports(List<NodeReport> nodeReports);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusRequest.java

@@ -18,18 +18,17 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
-import org.apache.hadoop.classification.InterfaceAudience.Private;
 import org.apache.hadoop.classification.InterfaceAudience.Public;
 import org.apache.hadoop.classification.InterfaceStability.Stable;
-import org.apache.hadoop.classification.InterfaceStability.Unstable;
 import org.apache.hadoop.yarn.api.ContainerManager;
 import org.apache.hadoop.yarn.api.records.ContainerId;
 import org.apache.hadoop.yarn.api.records.ContainerStatus;
 
 /**
  * <p>The request sent by the <code>ApplicationMaster</code> to the
- * <code>NodeManager</code> to get {@link ContainerStatus} of a container via
+ * <code>NodeManager</code> to get {@link ContainerStatus} of a container.</p>
- * {@link ContainerManager#getContainerStatus(GetContainerStatusRequest)}.</p>
+ * 
+ * @see ContainerManager#getContainerStatus(GetContainerStatusRequest)
  */
 @Public
 @Stable
@@ -44,7 +43,13 @@ public interface GetContainerStatusRequest {
   @Stable
   public abstract ContainerId getContainerId();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <code>ContainerId</code> of container for which to obtain the
+   * <code>ContainerStatus</code>
+   * @param containerId <code>ContainerId</code> of container for which to 
+   *                    obtain the <code>ContainerStatus</code>
+   */
+  @Public
+  @Stable
   public abstract void setContainerId(ContainerId containerId);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetContainerStatusResponse.java

@@ -28,8 +28,9 @@ 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> 
- * of a container via
+ * of a container.</p>
- * {@link ContainerManager#getContainerStatus(GetContainerStatusRequest)}.</p>
+ * 
+ * @see ContainerManager#getContainerStatus(GetContainerStatusRequest)
  */
 @Public
 @Stable

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationIdRequest.java

@@ -18,6 +18,19 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+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>
+ * 
+ * @see ClientRMProtocol#getNewApplicationId(GetNewApplicationIdRequest)
+ */
+@Public
+@Stable
 public interface GetNewApplicationIdRequest {
 
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetNewApplicationIdResponse.java

@@ -18,9 +18,33 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationId;
 
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to the client for 
+ * a request to a new {@link ApplicationId} for submitting applications.</p>
+ * 
+ * @see ClientRMProtocol#getNewApplicationId(GetNewApplicationIdRequest)
+ */
+@Public
+@Stable
 public interface GetNewApplicationIdResponse {
+  /**
+   * Get the <em>new</em> <code>ApplicationId</code> allocated by the 
+   * <code>ResourceManager</code>.
+   * @return <em>new</em> <code>ApplicationId</code> allocated by the 
+   *          <code>ResourceManager</code>
+   */
+  @Public
+  @Stable
   public abstract ApplicationId getApplicationId();
+
+  @Private
+  @Unstable
   public abstract void setApplicationId(ApplicationId applicationId);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueInfoRequest.java

@@ -18,17 +18,70 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p>The request sent by clients to get <em>queue information</em>
+ * from the <code>ResourceManager</code>.</p>
+ *
+ * @see ClientRMProtocol#getQueueInfo(GetQueueInfoRequest)
+ */
+@Public
+@Stable
 public interface GetQueueInfoRequest {
+  /**
+   * Get the <em>queue name</em> for which to get queue information.
+   * @return <em>queue name</em> for which to get queue information
+   */
   String getQueueName();
+  
+  /**
+   * Set the <em>queue name</em> for which to get queue information
+   * @param queueName <em>queue name</em> for which to get queue information
+   */
   void setQueueName(String queueName);
 
+  /**
+   * Is information about <em>active applications<e/m> required?
+   * @return <code>true</code> if applications' information is to be included,
+   *         else <code>false</code>
+   */
   boolean getIncludeApplications();
+
+  /**
+   * Should we get fetch information about <em>active applications</em>?
+   * @param includeApplications fetch information about <em>active 
+   *                            applications</em>?
+   */
   void setIncludeApplications(boolean includeApplications);
 
+  /**
+   * Is information about <em>child queues</em> required?
+   * @return <code>true</code> if information about child queues is required,
+   *         else <code>false</code>
+   */
   boolean getIncludeChildQueues();
+  
+  /**
+   * Should we fetch information about <em>child queues</em>?
+   * @param includeChildQueues fetch information about <em>child queues</em>?
+   */
   void setIncludeChildQueues(boolean includeChildQueues);
 
+  /**
+   * Is information on the entire <em>child queue hierarchy</em> required?
+   * @return <code>true</code> if information about entire hierarchy is 
+   *         required, <code>false</code> otherwise
+   */
   boolean getRecursive();
+  
+  /**
+   * Should we fetch information on the entire <em>child queue hierarchy</em>?
+   * @param recursive fetch information on the entire <em>child queue 
+   *                  hierarchy</em>?
+   */
   void setRecursive(boolean recursive);
 }
 

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueInfoResponse.java

@@ -18,9 +18,34 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.QueueInfo;
 
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to a client
+ * requesting information about queues in the system.</p>
+ *
+ * <p>The response includes a {@link QueueInfo} which has details such as
+ * queue name, used/total capacities, running applications, child queues etc
+ * .</p>
+ * 
+ * @see QueueInfo
+ * @see ClientRMProtocol#getQueueInfo(GetQueueInfoRequest)
+ */
+@Public
+@Stable
 public interface GetQueueInfoResponse {
+  /**
+   * Get the <code>QueueInfo</code> for the specified queue.
+   * @return <code>QueueInfo</code> for the specified queue
+   */
   QueueInfo getQueueInfo();
+  
+  @Private
+  @Unstable
   void setQueueInfo(QueueInfo queueInfo);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueUserAclsInfoRequest.java

@@ -18,6 +18,18 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+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>
+ *
+ * @see ClientRMProtocol#getQueueUserAcls(GetQueueUserAclsInfoRequest)
+ */
+@Public
+@Stable
 public interface GetQueueUserAclsInfoRequest {
 
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/GetQueueUserAclsInfoResponse.java

@@ -20,12 +20,39 @@ package org.apache.hadoop.yarn.api.protocolrecords;
 
 import java.util.List;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+import org.apache.hadoop.yarn.api.records.QueueACL;
 import org.apache.hadoop.yarn.api.records.QueueUserACLInfo;
 
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to clients
+ * seeking queue acls for the user.</p>
+ *
+ * <p>The response contains a list of {@link QueueUserACLInfo} which
+ * provides information about {@link QueueACL} per queue.</p>
+ * 
+ * @see QueueACL
+ * @see QueueUserACLInfo
+ * @see ClientRMProtocol#getQueueUserAcls(GetQueueUserAclsInfoRequest)
+ */
+@Public
+@Stable
 public interface GetQueueUserAclsInfoResponse {
 
+  /**
+   * Get the <code>QueueUserACLInfo</code> per queue for the user.
+   * @return <code>QueueUserACLInfo</code> per queue for the user
+   */
+  @Public
+  @Stable
   public List<QueueUserACLInfo> getUserAclsInfoList();
   
+  @Private
+  @Unstable
   public void setUserAclsInfoList(List<QueueUserACLInfo> queueUserAclsList);
   
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterRequest.java

@@ -27,9 +27,7 @@ import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
 
 /**
  * <p>The request sent by the <code>ApplicationMaster</code> to 
- * <code>ResourceManager</code> on registration via the 
+ * <code>ResourceManager</code> on registration.</p>
- * {@link AMRMProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)} 
- * api.</p>
  * 
  * <p>The registration includes details such as:
  *   <ul>
@@ -42,13 +40,15 @@ import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
  *     <li>Tracking URL</li>
  *   </ul>
  * </p>
+ * 
+ * @see AMRMProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)
  */
 @Public
 @Stable
 public interface RegisterApplicationMasterRequest {
 
   /**
-   * Get the {@link ApplicationAttemptId} being managed by the 
+   * Get the <code>ApplicationAttemptId</code> being managed by the 
    * <code>ApplicationMaster</code>.
    * @return <code>ApplicationAttemptId</code> being managed by the 
    *         <code>ApplicationMaster</code>
@@ -57,44 +57,69 @@ public interface RegisterApplicationMasterRequest {
   @Stable
   ApplicationAttemptId getApplicationAttemptId();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <code>ApplicationAttemptId</code> being managed by the 
+   * <code>ApplicationMaster</code>.
+   * @param applicationAttemptId <code>ApplicationAttemptId</code> being managed  
+   *                             by the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
 
   /**
-   * Get the host on which the <code>ApplicationMaster</code> is running.
+   * Get the <em>host</em> on which the <code>ApplicationMaster</code> is 
-   * @return host on which the <code>ApplicationMaster</code> is running
+   * running.
+   * @return <em>host</em> on which the <code>ApplicationMaster</code> is running
    */
   @Public
   @Stable
   String getHost();
   
+  /**
+   * Set the <em>host</em> on which the <code>ApplicationMaster</code> is 
+   * running.
+   * @param host <em>host</em> on which the <code>ApplicationMaster</code> 
+   *             is running
+   */
   @Private
   @Unstable
   void setHost(String host);
 
   /**
-   * Get the RPC port on which the <code>ApplicationMaster</code> is responding. 
+   * Get the <em>RPC port</em> on which the <code>ApplicationMaster</code> 
-   * @return the RPC port on which the <code>ApplicationMaster</code> is 
+   * is responding. 
+   * @return the <em>RPC port<em> on which the <code>ApplicationMaster</code> is 
    *         responding
    */
   @Public
   @Stable
   int getRpcPort();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <em>RPC port<em> on which the <code>ApplicationMaster</code> is 
+   * responding.
+   * @param port <em>RPC port<em> on which the <code>ApplicationMaster</code> is 
+   *             responding
+   */
+  @Public
+  @Stable
   void setRpcPort(int port);
 
   /**
-   * Get the tracking URL for the <code>ApplicationMaster</code>.
+   * Get the <em>tracking URL</em> for the <code>ApplicationMaster</code>.
-   * @return the tracking URL for the <code>ApplicationMaster</code>
+   * @return <em>tracking URL</em> for the <code>ApplicationMaster</code>
    */
   @Public
   @Stable
   String getTrackingUrl();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <em>tracking URL</em> for the <code>ApplicationMaster</code>.
-  void setTrackingUrl(String string);
+   * @param trackingUrl <em>tracking URL</em> for the 
+   *                    <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  void setTrackingUrl(String trackingUrl);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterResponse.java

@@ -27,9 +27,7 @@ import org.apache.hadoop.yarn.api.records.Resource;
 
 /**
  * <p>The response sent by the <code>ResourceManager</code> to a new 
- * <code>ApplicationMaster</code> on registration via the 
+ * <code>ApplicationMaster</code> on registration.</p>
- * {@link AMRMProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)} 
- * api.</p>
  * 
  * <p>The response contains critical details such as:
  * <ul>
@@ -37,6 +35,8 @@ import org.apache.hadoop.yarn.api.records.Resource;
  *   <li>Maximum capability for allocated resources in the cluster.</li>
  * </ul>
  * </p>
+ * 
+ * @see AMRMProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)
  */
 @Public
 @Stable

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerRequest.java

@@ -18,17 +18,14 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
-import org.apache.hadoop.classification.InterfaceAudience.Private;
 import org.apache.hadoop.classification.InterfaceAudience.Public;
 import org.apache.hadoop.classification.InterfaceStability.Stable;
-import org.apache.hadoop.classification.InterfaceStability.Unstable;
 import org.apache.hadoop.yarn.api.ContainerManager;
 import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
 
 /**
  * <p>The request sent by the <code>ApplicationMaster</code> to the
- * <code>NodeManager</code> to <em>start</em> a container via
+ * <code>NodeManager</code> to <em>start</em> a container.</p>
- * {@link ContainerManager#startContainer(StartContainerRequest)}.</p>
  * 
  * <p>The <code>ApplicationMaster</code> has to provide details such as
  * allocated resource capability, security tokens (if enabled), command
@@ -36,6 +33,7 @@ import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
  * necessary binaries/jar/shared-objects etc. via the 
  * {@link ContainerLaunchContext}.</p>
  *
+ * @see ContainerManager#startContainer(StartContainerRequest)
  */
 @Public
 @Stable
@@ -51,7 +49,13 @@ public interface StartContainerRequest {
   @Stable
   public abstract ContainerLaunchContext getContainerLaunchContext();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <code>ContainerLaunchContext</code> for the container to be started
+   * by the <code>NodeManager</code>
+   * @param context <code>ContainerLaunchContext</code> for the container to be 
+   *                started by the <code>NodeManager</code>
+   */
+  @Public
+  @Stable
   public abstract void setContainerLaunchContext(ContainerLaunchContext context);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StartContainerResponse.java

@@ -25,8 +25,9 @@ import org.apache.hadoop.yarn.api.ContainerManager;
 /**
  * <p>The response sent by the <code>NodeManager</code> to the 
  * <code>ApplicationMaster</code> when asked to <em>start</em> an
- * allocated container via
+ * allocated container.</p>
- * {@link ContainerManager#startContainer(StartContainerRequest)}.</p>
+ * 
+ * @see ContainerManager#startContainer(StartContainerRequest)
  */
 @Public
 @Stable

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerRequest.java

@@ -18,17 +18,16 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
-import org.apache.hadoop.classification.InterfaceAudience.Private;
 import org.apache.hadoop.classification.InterfaceAudience.Public;
 import org.apache.hadoop.classification.InterfaceStability.Stable;
-import org.apache.hadoop.classification.InterfaceStability.Unstable;
 import org.apache.hadoop.yarn.api.ContainerManager;
 import org.apache.hadoop.yarn.api.records.ContainerId;
 
 /**
  * <p>The request sent by the <code>ApplicationMaster</code> to the
- * <code>NodeManager</code> to <em>stop</em> a container via
+ * <code>NodeManager</code> to <em>stop</em> a container.</p>
- * {@link ContainerManager#stopContainer(StopContainerRequest)}.</p>
+ * 
+ * @see ContainerManager#stopContainer(StopContainerRequest)
  */
 @Public
 @Stable
@@ -41,7 +40,11 @@ public interface StopContainerRequest {
   @Stable
   ContainerId getContainerId();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <code>ContainerId</code> of the container to be stopped.
+   * @param containerId <code>ContainerId</code> of the container to be stopped
+   */
+  @Public
+  @Stable
   void setContainerId(ContainerId containerId);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/StopContainerResponse.java

@@ -25,8 +25,9 @@ import org.apache.hadoop.yarn.api.ContainerManager;
 /**
  * <p>The response sent by the <code>NodeManager</code> to the 
  * <code>ApplicationMaster</code> when asked to <em>stop</em> an
- * allocated container via
+ * allocated container.</p>
- * {@link ContainerManager#stopContainer(StopContainerRequest)}.</p>
+ * 
+ * @see ContainerManager#stopContainer(StopContainerRequest)
  */
 @Public
 @Stable

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/SubmitApplicationRequest.java

@@ -18,9 +18,43 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationSubmissionContext;
+import org.apache.hadoop.yarn.api.records.ContainerLaunchContext;
+import org.apache.hadoop.yarn.api.records.Resource;
 
+/**
+ * <p>The request sent by a client to <em>submit an application</em> to the 
+ * <code>ResourceManager</code>.</p>
+ * 
+ * <p>The request, via {@link ApplicationSubmissionContext}, contains
+ * details such as queue, {@link Resource} required to run the 
+ * <code>ApplicationMaster</code>, the equivalent of 
+ * {@link ContainerLaunchContext} for launching the 
+ * <code>ApplicationMaster</code> etc.
+ * 
+ * @see ClientRMProtocol#submitApplication(SubmitApplicationRequest)
+ */
+@Public
+@Stable
 public interface SubmitApplicationRequest {
+  /**
+   * Get the <code>ApplicationSubmissionContext</code> for the application.
+   * @return <code>ApplicationSubmissionContext</code> for the application
+   */
+  @Public
+  @Stable
   public abstract ApplicationSubmissionContext getApplicationSubmissionContext();
-  public abstract void setApplicationSubmissionContext(ApplicationSubmissionContext context);
+
+  /**
+   * Set the <code>ApplicationSubmissionContext</code> for the application.
+   * @param context <code>ApplicationSubmissionContext</code> for the 
+   *                application
+   */
+  @Public
+  @Stable
+  public abstract void setApplicationSubmissionContext(
+      ApplicationSubmissionContext context);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/SubmitApplicationResponse.java

@@ -18,6 +18,18 @@
 
 package org.apache.hadoop.yarn.api.protocolrecords;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to a client on
+ * application submission.</p>
+ * 
+ * @see ClientRMProtocol#submitApplication(SubmitApplicationRequest)
+ */
+@Public
+@Stable
 public interface SubmitApplicationResponse {
 
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java

@@ -29,8 +29,7 @@ import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest;
 
 /**
  * <p>The response sent by the <code>ResourceManager</code> the  
- * <code>ApplicationMaster</code> during resource negotiation via
+ * <code>ApplicationMaster</code> during resource negotiation.</p>
- * {@link AMRMProtocol#allocate(AllocateRequest)}.</p>
  *
  * <p>The response includes:
  *   <ul>
@@ -46,6 +45,8 @@ import org.apache.hadoop.yarn.api.protocolrecords.AllocateRequest;
  *     </li>
  *   </ul>
  * </p>
+ * 
+ * @see AMRMProtocol#allocate(AllocateRequest)
  */
 @Public
 @Unstable
@@ -67,8 +68,8 @@ public interface AMResponse {
   public void setReboot(boolean reboot);
 
   /**
-   * Get the last response id.
+   * Get the <em>last response id</em>.
-   * @return the last response id
+   * @return <em>last response id</em>
    */
   @Public
   @Stable
@@ -79,9 +80,9 @@ public interface AMResponse {
   public void setResponseId(int responseId);
 
   /**
-   * Get the list of newly allocated {@link Container} by the 
+   * Get the list of <em>newly allocated</em> <code>Container</code> by the 
    * <code>ResourceManager</code>.
-   * @return list of newly allocated <code>Container</code> 
+   * @return list of <em>newly allocated</em> <code>Container</code>
    */
   @Public
   @Stable
@@ -112,7 +113,10 @@ public interface AMResponse {
   public void clearNewContainers();
   
   /**
-   * Get available headroom for resources in the cluster for the application.
+   * 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 
+   * application
    */
   @Public
   @Stable
@@ -123,8 +127,8 @@ public interface AMResponse {
   public void setAvailableResources(Resource limit);
   
   /**
-   * Get the list of completed containers.
+   * Get the list of <em>completed containers</em>.
-   * @return the list of completed containers
+   * @return the list of <em>completed containers</em>
    */
   @Public
   @Stable

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationReport.java

@@ -18,38 +18,172 @@
 
 package org.apache.hadoop.yarn.api.records;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p><code>ApplicationReport</code> is a report of an application.</p>
+ *
+ * <p>It includes details such as:
+ *   <ul>
+ *     <li>{@link ApplicationId} of the application.</li>
+ *     <li>Applications user.</li>
+ *     <li>Application queue.</li>
+ *     <li>Application name.</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 ApplicationState} of the application.</li>
+ *     <li>Diagnostic information in case of errors.</li>
+ *     <li>Start time of the application.</li>
+ *     <li>Client token of the application (if security is enabled).</li>
+ *   </ul>
+ * </p>
+ * 
+ * @see ClientRMProtocol#getApplicationReport(org.apache.hadoop.yarn.api.protocolrecords.GetApplicationReportRequest)
+ */
+@Public
+@Stable
 public interface ApplicationReport {
 
+  /**
+   * Get the <code>ApplicationId</code> of the application.
+   * @return <code>ApplicationId</code> of the application
+   */
+  @Public
+  @Stable
   ApplicationId getApplicationId();
+  
+  @Private
+  @Unstable
   void setApplicationId(ApplicationId applicationId);
 
+  /**
+   * Get the <em>user</em> who submitted the application.
+   * @return <em>user</em> who submitted the application
+   */
+  @Public
+  @Stable
   String getUser();
+  
+  @Private
+  @Unstable
   void setUser(String user);
 
+  /**
+   * Get the <em>queue</em> to which the application was submitted.
+   * @return <em>queue</em> to which the application was submitted
+   */
+  @Public
+  @Stable
   String getQueue();
+  
+  @Private
+  @Unstable
   void setQueue(String queue);
 
+  /**
+   * Get the user-defined <em>name</em> of the application.
+   * @return <em>name</em> of the application
+   */
+  @Public
+  @Stable
   String getName();
+  
+  @Private
+  @Unstable
   void setName(String name);
 
+  /**
+   * Get the <em>host</em> on which the <code>ApplicationMaster</code> 
+   * is running.
+   * @return <em>host</em> on which the <code>ApplicationMaster</code> 
+   *         is running
+   */
+  @Public
+  @Stable
   String getHost();
+  
+  @Private
+  @Unstable
   void setHost(String host);
 
+  /**
+   * Get the <em>RPC port</em> of the <code>ApplicationMaster</code>.
+   * @return <em>RPC port</em> of the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   int getRpcPort();
+  
+  @Private
+  @Unstable
   void setRpcPort(int rpcPort);
 
+  /**
+   * Get the <em>client token</em> for communicating with the 
+   * <code>ApplicationMaster</code>.
+   * @return <em>client token</em> for communicating with the 
+   * <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   String getClientToken();
+  
+  @Private
+  @Unstable
   void setClientToken(String clientToken);
 
+  /**
+   * Get the <code>ApplicationState</code> of the application.
+   * @return <code>ApplicationState</code> of the application
+   */
+  @Public
+  @Stable
   ApplicationState getState();
+  
+  @Private
+  @Unstable
   void setState(ApplicationState state);
 
+  /**
+   * Get  the <em>diagnositic information</em> of the application in case of 
+   * errors.
+   * @return <em>diagnositic information</em> of the application in case 
+   *         of errors
+   */
+  @Public
+  @Stable
   String getDiagnostics();
+  
+  @Private
+  @Unstable
   void setDiagnostics(String diagnostics);
 
+  /**
+   * Get the <em>tracking url</em> for the application.
+   * @return <em>tracking url</em> for the application
+   */
+  @Public
+  @Stable
   String getTrackingUrl();
+  
+  @Private
+  @Unstable
   void setTrackingUrl(String url);
   
+  /**
+   * Get the <em>start time</em> of the application.
+   * @return <em>start time</em> of the application
+   */
+  @Public
+  @Stable
   long getStartTime();
+  
+  @Private
+  @Unstable
   void setStartTime(long startTime);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ApplicationSubmissionContext.java

@@ -22,68 +22,319 @@ import java.nio.ByteBuffer;
 import java.util.List;
 import java.util.Map;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p><code>ApplicationSubmissionContext</code> represents the all of the 
+ * information needed by the <code>ResourceManager</code> to launch 
+ * the <code>ApplicationMaster</code> for an application.</p>
+ * 
+ * <p>It includes details such as:
+ *   <ul>
+ *     <li>{@link ApplicationId} of the application.</li>
+ *     <li>
+ *       {@link Resource} necessary to run the <code>ApplicationMaster</code>.
+ *     </li>
+ *     <li>Application user.</li>
+ *     <li>Application name.</li>
+ *     <li>{@link Priority} of the application.</li>
+ *     <li>Security tokens (if security is enabled).</li>
+ *     <li>
+ *       {@link LocalResource} necessary for running the 
+ *       <code>ApplicationMaster</code> container such
+ *       as binaries, jar, shared-objects, side-files etc. 
+ *     </li>
+ *     <li>
+ *       Environment variables for the launched <code>ApplicationMaster</code> 
+ *       process.
+ *     </li>
+ *     <li>Command to launch the <code>ApplicationMaster</code>.</li>
+ *   </ul>
+ * </p>
+ * 
+ * @see ClientRMProtocol#submitApplication(org.apache.hadoop.yarn.api.protocolrecords.SubmitApplicationRequest)
+ */
+@Public
+@Stable
 public interface ApplicationSubmissionContext {
-  public abstract ApplicationId getApplicationId();
+  /**
-  public abstract String getApplicationName();
+   * Get the <code>ApplicationId</code> of the submitted application.
-  public abstract Resource getMasterCapability();
+   * @return <code>ApplicationId</code> of the submitted application
+   */
+  @Public
+  @Stable
+  public ApplicationId getApplicationId();
   
-  public abstract Map<String, URL> getAllResources();
+  /**
-  public abstract URL getResource(String key);
+   * Set the <code>ApplicationId</code> of the submitted application.
+   * @param appplicationId <code>ApplicationId</code> of the submitted 
+   *                       application
+   */
+  @Public
+  @Stable
+  public void setApplicationId(ApplicationId appplicationId);
 
-  public abstract Map<String, LocalResource> getAllResourcesTodo();
+  /**
-  public abstract LocalResource getResourceTodo(String key);
+   * Get the application <em>name</em>.
+   * @return application name
+   */
+  @Public
+  @Stable
+  public String getApplicationName();
   
-  public abstract List<String> getFsTokenList();
+  /**
-  public abstract String getFsToken(int index);
+   * Set the application <em>name</em>.
-  public abstract int getFsTokenCount();
+   * @param applicationName application name
+   */
+  @Public
+  @Stable
+  public void setApplicationName(String applicationName);
   
-  public abstract ByteBuffer getFsTokensTodo();
+  /**
+   * Get the <em>queue</em> to which the application is being submitted.
+   * @return <em>queue</em> to which the application is being submitted
+   */
+  @Public
+  @Stable
+  public String getQueue();
   
-  public abstract Map<String, String> getAllEnvironment();
+  /**
-  public abstract String getEnvironment(String key);
+   * Set the <em>queue</em> to which the application is being submitted
+   * @param queue <em>queue</em> to which the application is being submitted
+   */
+  @Public
+  @Stable
+  public void setQueue(String queue);
   
-  public abstract List<String> getCommandList();
+  /**
-  public abstract String getCommand(int index);
+   * Get the <code>Priority</code> of the application.
-  public abstract int getCommandCount();
+   * @return <code>Priority</code> of the application
+   */
+  @Public
+  @Stable
+  public Priority getPriority();
 
-  public abstract String getQueue();
+  /**
-  public abstract Priority getPriority();
+   * Set the <code>Priority</code> of the application.
-  public abstract String getUser();
+   * @param priority <code>Priority</code> of the application
+   */
+  @Public
+  @Stable
+  public void setPriority(Priority priority);
   
+  /**
+   * Get the <em>user</em> submitting the application.
+   * @return <em>user</em> submitting the application
+   */
+  @Public
+  @Stable
+  public String getUser();
   
+  /**
+   * Set the <em>user</em> submitting the application.
+   * @param user <em>user</em> submitting the application
+   */
+  @Public
+  @Stable
+  public void setUser(String user);
   
-  public abstract void setApplicationId(ApplicationId appplicationId);
+  /**
-  public abstract void setApplicationName(String applicationName);
+   * Get the <code>Resource</code> required to run the 
-  public abstract void setMasterCapability(Resource masterCapability);
+   * <code>ApplicationMaster</code>.
+   * @return <code>Resource</code> required to run the 
+   *         <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public Resource getMasterCapability();
   
-  public abstract void addAllResources(Map<String, URL> resources);
+  /**
-  public abstract void setResource(String key, URL url);
+   * Set <code>Resource</code> required to run the 
-  public abstract void removeResource(String key);
+   * <code>ApplicationMaster</code>.
-  public abstract void clearResources();
+   * @param masterCapability <code>Resource</code> required to run the 
+   *                         <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public void setMasterCapability(Resource masterCapability);
   
-  public abstract void addAllResourcesTodo(Map<String, LocalResource> resourcesTodo);
+  @Private
-  public abstract void setResourceTodo(String key, LocalResource localResource);
+  @Unstable
-  public abstract void removeResourceTodo(String key);
+  public Map<String, URL> getAllResources();
-  public abstract void clearResourcesTodo();
   
-  public abstract void addAllFsTokens(List<String> fsTokens);
+  @Private
-  public abstract void addFsToken(String fsToken);
+  @Unstable
-  public abstract void removeFsToken(int index);
+  public URL getResource(String key);
-  public abstract void clearFsTokens();
   
-  public abstract void setFsTokensTodo(ByteBuffer fsTokensTodo);
+  @Private
+  @Unstable
+  public void addAllResources(Map<String, URL> resources);
 
-  public abstract void addAllEnvironment(Map<String, String> environment);
+  @Private
-  public abstract void setEnvironment(String key, String env);
+  @Unstable
-  public abstract void removeEnvironment(String key);
+  public void setResource(String key, URL url);
-  public abstract void clearEnvironment();
 
-  public abstract void addAllCommands(List<String> commands);
+  @Private
-  public abstract void addCommand(String command);
+  @Unstable
-  public abstract void removeCommand(int index);
+  public void removeResource(String key);
-  public abstract void clearCommands();
 
-  public abstract void setQueue(String queue);
+  @Private
-  public abstract void setPriority(Priority priority);
+  @Unstable
-  public abstract void setUser(String user);
+  public void clearResources();
+
+  /**
+   * Get all the <code>LocalResource</code> required to run the 
+   * <code>ApplicationMaster</code>.
+   * @return <code>LocalResource</code> required to run the 
+   *         <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public Map<String, LocalResource> getAllResourcesTodo();
+  
+  @Private
+  @Unstable
+  public LocalResource getResourceTodo(String key);
+  
+  /**
+   * Add all the <code>LocalResource</code> required to run the 
+   * <code>ApplicationMaster</code>.
+   * @param resources all <code>LocalResource</code> required to run the 
+   *                      <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public void addAllResourcesTodo(Map<String, LocalResource> resources);
+
+  @Private
+  @Unstable
+  public void setResourceTodo(String key, LocalResource localResource);
+
+  @Private
+  @Unstable
+  public void removeResourceTodo(String key);
+
+  @Private
+  @Unstable
+  public void clearResourcesTodo();
+
+  @Private
+  @Unstable
+  public List<String> getFsTokenList();
+  
+  @Private
+  @Unstable
+  public String getFsToken(int index);
+  
+  @Private
+  @Unstable
+  public int getFsTokenCount();
+  
+  @Private
+  @Unstable
+  public void addAllFsTokens(List<String> fsTokens);
+
+  @Private
+  @Unstable
+  public void addFsToken(String fsToken);
+
+  @Private
+  @Unstable
+  public void removeFsToken(int index);
+
+  @Private
+  @Unstable
+  public void clearFsTokens();
+
+  /**
+   * Get <em>file-system tokens</em> for the <code>ApplicationMaster</code>.
+   * @return file-system tokens for the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public ByteBuffer getFsTokensTodo();
+  
+  /**
+   * Set <em>file-system tokens</em> for the <code>ApplicationMaster</code>.
+   * @param fsTokens file-system tokens for the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public void setFsTokensTodo(ByteBuffer fsTokens);
+
+  /**
+   * Get the <em>environment variables</em> for the 
+   * <code>ApplicationMaster</code>.
+   * @return environment variables for the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public Map<String, String> getAllEnvironment();
+  
+  @Private
+  @Unstable
+  public String getEnvironment(String key);
+  
+  /**
+   * Add all of the <em>environment variables</em> for the 
+   * <code>ApplicationMaster</code>.
+   * @param environment environment variables for the 
+   *                    <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public void addAllEnvironment(Map<String, String> environment);
+
+  @Private
+  @Unstable
+  public void setEnvironment(String key, String env);
+
+  @Private
+  @Unstable
+  public void removeEnvironment(String key);
+
+  @Private
+  @Unstable
+  public void clearEnvironment();
+
+  /**
+   * Get the <em>commands</em> to launch the <code>ApplicationMaster</code>.
+   * @return commands to launch the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public List<String> getCommandList();
+  
+  @Private
+  @Unstable
+  public String getCommand(int index);
+  
+  @Private
+  @Unstable
+  public int getCommandCount();
+  
+  /**
+   * Add all of the <em>commands</em> to launch the 
+   * <code>ApplicationMaster</code>.
+   * @param commands commands to launch the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
+  public void addAllCommands(List<String> commands);
+  
+  @Private
+  @Unstable
+  public void addCommand(String command);
+  
+  @Private
+  @Unstable
+  public void removeCommand(int index);
+  
+  @Private
+  @Unstable
+  public void clearCommands();
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/ContainerLaunchContext.java

@@ -26,6 +26,7 @@ import org.apache.hadoop.classification.InterfaceAudience.Private;
 import org.apache.hadoop.classification.InterfaceAudience.Public;
 import org.apache.hadoop.classification.InterfaceStability.Stable;
 import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ContainerManager;
 
 /**
  * <p><code>ContainerLaunchContext</code> represents the all of the information
@@ -43,17 +44,11 @@ import org.apache.hadoop.classification.InterfaceStability.Unstable;
  *     </li>
  *     <li>Optional, application-specific binary service data.</li>
  *     <li>Environment variables for the launched process.</li>
- *     <li>Command to be executed to launch the container.</li>
+ *     <li>Command to launch the container.</li>
- *     <li></li>
- *     <li></li>
- *     <li></li>
- *     <li></li>
- *     <li></li>
- *     <li></li>
- *     <li></li>
- *     <li></li>
  *   </ul>
  * </p>
+ * 
+ * @see ContainerManager#startContainer(org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest)
  */
 @Public
 @Stable
@@ -66,8 +61,12 @@ public interface ContainerLaunchContext {
   @Stable
   ContainerId getContainerId();
 
-  @Private
+  /**
-  @Unstable
+   * Set <code>ContainerId</code> of container to be launched.
+   * @param containerId et <code>ContainerId</code> of container to be launched
+   */
+  @Public
+  @Stable
   void setContainerId(ContainerId containerId);
 
   /**
@@ -78,8 +77,12 @@ public interface ContainerLaunchContext {
   @Stable
   String getUser();
   
-  @Private
+  /**
-  @Unstable
+   * Set the <em>user</em> to whom the container has been allocated
+   * @param user <em>user</em> to whom the container has been allocated
+   */
+  @Public
+  @Stable
   void setUser(String user);
 
   /**
@@ -92,8 +95,13 @@ public interface ContainerLaunchContext {
   @Stable
   Resource getResource();
 
-  @Private
+  /**
-  @Unstable
+   * Set the <code>Resource</code> allocated to the container by the
+   * <code>ResourceManager</code>.
+   * @param resource allocated resource
+   */
+  @Public
+  @Stable
   void setResource(Resource resource);
 
   /**
@@ -104,8 +112,12 @@ public interface ContainerLaunchContext {
   @Stable
   ByteBuffer getContainerTokens();
 
-  @Private
+  /**
-  @Unstable
+   * Set security tokens (if security is enabled).
+   * @param containerToken security tokens 
+   */
+  @Public
+  @Stable
   void setContainerTokens(ByteBuffer containerToken);
 
   /**
@@ -120,8 +132,12 @@ public interface ContainerLaunchContext {
   @Unstable
   LocalResource getLocalResource(String key);
 
-  @Private
+  /**
-  @Unstable
+   * Add all <code>LocalResource</code> required by the container.
+   * @param localResources <code>LocalResource</code> required by the container
+   */
+  @Public
+  @Stable
   void addAllLocalResources(Map<String, LocalResource> localResources);
 
   @Private
@@ -148,8 +164,12 @@ public interface ContainerLaunchContext {
   @Unstable
   ByteBuffer getServiceData(String key);
 
-  @Private
+  /**
-  @Unstable
+   * Add add application-specific binary service data.
+   * @param serviceData application-specific binary service data
+   */
+  @Public
+  @Stable
   void addAllServiceData(Map<String, ByteBuffer> serviceData);
 
   @Private
@@ -176,8 +196,12 @@ public interface ContainerLaunchContext {
   @Unstable
   String getEnv(String key);
   
-  @Private
+  /**
-  @Unstable
+   * Add <em>environment variables</em> for the launched container.
+   * @param env <em>environment variables</em> for the launched container
+   */
+  @Public
+  @Stable
   void addAllEnv(Map<String, String> env);
 
   @Private
@@ -208,8 +232,12 @@ public interface ContainerLaunchContext {
   @Unstable
   int getCommandCount();
   
-  @Private
+  /**
-  @Unstable
+   * Add the list of <em>commands</em> for launching the container.
+   * @param commands the list of <em>commands</em> for launching the container
+   */
+  @Public
+  @Stable
   void addAllCommands(List<String> commands);
   
   @Private

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/LocalResource.java

@@ -18,16 +18,92 @@
 
 package org.apache.hadoop.yarn.api.records;
 
-public interface LocalResource {
+import org.apache.hadoop.classification.InterfaceAudience.Public;
-  public abstract URL getResource();
+import org.apache.hadoop.classification.InterfaceStability.Stable;
-  public abstract long getSize();
+import org.apache.hadoop.yarn.api.ContainerManager;
-  public abstract long getTimestamp();
-  public abstract LocalResourceType getType();
-  public abstract LocalResourceVisibility getVisibility();
 
-  public abstract void setResource(URL resource);
+/**
-  public abstract void setSize(long size);
+ * <p><code>LocalResource</code> represents a local resource required to
-  public abstract void setTimestamp(long timestamp);
+ * run a container.</p>
-  public abstract void setType(LocalResourceType type);
+ * 
-  public abstract void setVisibility(LocalResourceVisibility visibility);
+ * <p>The <code>NodeManager</code> is responsible for localizing the resource 
+ * prior to launching the container.</p>
+ * 
+ * <p>Applications can specify {@link LocalResourceType} and 
+ * {@link LocalResourceVisibility}.</p>
+ * 
+ * @see LocalResourceType
+ * @see LocalResourceVisibility
+ * @see ContainerLaunchContext
+ * @see ApplicationSubmissionContext
+ * @see ContainerManager#startContainer(org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest)
+ */
+@Public
+@Stable
+public interface LocalResource {
+  /**
+   * Get the <em>location</em> of the resource to be localized.
+   * @return <em>location</em> of the resource to be localized
+   */
+  public URL getResource();
+  
+  /**
+   * Set <em>location</em> of the resource to be localized.
+   * @param resource <em>location</em> of the resource to be localized
+   */
+  public void setResource(URL resource);
+  
+  /**
+   * Get the <em>size</em> of the resource to be localized.
+   * @return <em>size</em> of the resource to be localized
+   */
+  public long getSize();
+  
+  /**
+   * Set the <em>size</em> of the resource to be localized.
+   * @param size <em>size</em> of the resource to be localized
+   */
+  public void setSize(long size);
+  
+  /**
+   * Get the original <em>timestamp</em> of the resource to be localized, used
+   * for verification.
+   * @return <em>timestamp</em> of the resource to be localized
+   */
+  public long getTimestamp();
+  
+  /**
+   * Set the <em>timestamp</em> of the resource to be localized, used
+   * for verification.
+   * @param timestamp <em>timestamp</em> of the resource to be localized
+   */
+  public void setTimestamp(long timestamp);
+  
+  /**
+   * Get the <code>LocalResourceType</code> of the resource to be localized.
+   * @return <code>LocalResourceType</code> of the resource to be localized
+   */
+  public LocalResourceType getType();
+  
+  /**
+   * Set the <code>LocalResourceType</code> of the resource to be localized.
+   * @param type <code>LocalResourceType</code> of the resource to be localized
+   */
+  public void setType(LocalResourceType type);
+  
+  /**
+   * Get the <code>LocalResourceVisibility</code> of the resource to be 
+   * localized.
+   * @return <code>LocalResourceVisibility</code> of the resource to be 
+   *         localized
+   */
+  public LocalResourceVisibility getVisibility();
+  
+  /**
+   * Set the <code>LocalResourceVisibility</code> of the resource to be 
+   * localized.
+   * @param visibility <code>LocalResourceVisibility</code> of the resource to be 
+   *                   localized
+   */
+  public void setVisibility(LocalResourceVisibility visibility);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/LocalResourceType.java

@@ -18,6 +18,42 @@
 
 package org.apache.hadoop.yarn.api.records;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ContainerManager;
+
+/**
+ * <p><code>LocalResourceType</code> specifies the <em>type</em>
+ * of a resource localized by the <code>NodeManager</code>.</p> 
+ *
+ * <p>The <em>type</em> can be one of:
+ *   <ul>
+ *     <li>
+ *       {@link #FILE} - Regular file i.e. uninterpreted bytes. 
+ *     </li>
+ *     <li>
+ *       {@link #ARCHIVE} - Archive, which is automatically unarchived by the 
+ *       <code>NodeManager</code>.
+ *     </li>
+ *   </ul>
+ * </p>
+ *
+ * @see LocalResource
+ * @see ContainerLaunchContext
+ * @see ApplicationSubmissionContext
+ * @see ContainerManager#startContainer(org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest)
+ */
+@Public
+@Stable
 public enum LocalResourceType {
-  ARCHIVE, FILE
+  
+  /**
+   * Archive, which is automatically unarchived by the <code>NodeManager</code>.
+   */
+  ARCHIVE,
+  
+  /**
+   * Regular file i.e. uninterpreted bytes.
+   */
+  FILE
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/LocalResourceVisibility.java

@@ -18,6 +18,48 @@
 
 package org.apache.hadoop.yarn.api.records;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ContainerManager;
+
+/**
+ * <p><code>LocalResourceVisibility</code> specifies the <em>visibility</em>
+ * of a resource localized by the <code>NodeManager</code>.</p>
+ * 
+ * <p>The <em>visibility</em> can be one of:
+ *   <ul>
+ *     <li>{@link #PUBLIC} - Shared by all users on the node.</li>
+ *     <li>
+ *       {@link #PRIVATE} - Shared among all applications of the 
+ *       <em>same user</em> on the node.
+ *     </li>
+ *     <li>
+ *       {@link #APPLICATION} - Shared only among containers of the 
+ *       <em>same application</em> on the node.
+ *     </li>
+ *   </ul>
+ * </p>
+ * 
+ * @see LocalResource
+ * @see ContainerLaunchContext
+ * @see ApplicationSubmissionContext
+ * @see ContainerManager#startContainer(org.apache.hadoop.yarn.api.protocolrecords.StartContainerRequest)
+ */
+@Public
+@Stable
 public enum LocalResourceVisibility {
-  PUBLIC, PRIVATE, APPLICATION
+  /** 
+   * Shared by all users on the node.
+   */
+  PUBLIC, 
+  
+  /** 
+   * Shared among all applications of the <em>same user</em> on the node.
+   */
+  PRIVATE, 
+  
+  /** 
+   * Shared only among containers of the <em>same application</em> on the node.
+   */
+  APPLICATION
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/NodeHealthStatus.java

@@ -17,17 +17,69 @@
  */
 package org.apache.hadoop.yarn.api.records;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p><code>NodeHealthStatus</code> is a summary of the health status of the
+ * node.</p>
+ *
+ * <p>It includes information such as:
+ *   <ul>
+ *     <li>
+ *       An indicator of whether the node is healthy, as determined by the 
+ *       health-check script.
+ *     </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>
+ * 
+ * @see NodeReport
+ * @see ClientRMProtocol#getClusterNodes(org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest)
+ */
+@Public
+@Stable
 public interface NodeHealthStatus {
 
+  /**
+   * Is the node healthy?
+   * @return <code>true</code> if the node is healthy, else <code>false</code>
+   */
+  @Public
+  @Stable
   boolean getIsNodeHealthy();
 
-  String getHealthReport();
+  @Private
-
+  @Unstable
-  long getLastHealthReportTime();
-
   void setIsNodeHealthy(boolean isNodeHealthy);
 
+  /**
+   * Get the <em>diagnostic health report</em> of the node.
+   * @return <em>diagnostic health report</em> of the node
+   */
+  @Public
+  @Stable
+  String getHealthReport();
+
+  @Private
+  @Unstable
   void setHealthReport(String healthReport);
 
+  /**
+   * Get the <em>last timestamp</em> at which the health report was received.
+   * @return <em>last timestamp</em> at which the health report was received
+   */
+  @Public
+  @Stable
+  long getLastHealthReportTime();
+
+  @Private
+  @Unstable
   void setLastHealthReportTime(long lastHealthReport);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/NodeReport.java

@@ -18,19 +18,113 @@
 
 package org.apache.hadoop.yarn.api.records;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p><code>NodeReport</code> is a summary of runtime information of a 
+ * node in the cluster.</p>
+ * 
+ * <p>It includes details such as:
+ *   <ul>
+ *     <li>{@link NodeId} of the node.</li>
+ *     <li>HTTP Tracking URL of the node.</li>
+ *     <li>Rack name for the node.</li>
+ *     <li>Used {@link Resource} on the node.</li>
+ *     <li>Total available {@link Resource} of the node.</li>
+ *     <li>Number of running containers on the node.</li>
+ *     <li>{@link NodeHealthStatus} of the node.</li>
+ *   </ul>
+ * </p>
+ *
+ * @see NodeHealthStatus
+ * @see ClientRMProtocol#getClusterNodes(org.apache.hadoop.yarn.api.protocolrecords.GetClusterNodesRequest)
+ */
+@Public
+@Stable
 public interface NodeReport {
+  /**
+   * Get the <code>NodeId</code> of the node.
+   * @return <code>NodeId</code> of the node
+   */
   NodeId getNodeId();
+  
+  @Private
+  @Unstable
   void setNodeId(NodeId nodeId);
+  
+  /**
+   * Get the <em>http address</em> of the node.
+   * @return <em>http address</em> of the node
+   */
+  @Public
+  @Stable
   String getHttpAddress();
+  
+  @Private
+  @Unstable
   void setHttpAddress(String httpAddress);
+  
+  /**
+   * Get the <em>rack name</em> for the node.
+   * @return <em>rack name</em> for the node
+   */
+  @Public
+  @Stable
   String getRackName();
+  
+  @Private
+  @Unstable
   void setRackName(String rackName);
+  
+  /**
+   * Get <em>used</em> <code>Resource</code> on the node.
+   * @return <em>used</em> <code>Resource</code> on the node
+   */
+  @Public
+  @Stable
   Resource getUsed();        
+  
+  @Private
+  @Unstable
   void setUsed(Resource used);
+  
+  /**
+   * Get the <em>total</em> <code>Resource</code> on the node.
+   * @return <em>total</em> <code>Resource</code> on the node
+   */
+  @Public
+  @Stable
   Resource getCapability();
+  
+  @Private
+  @Unstable
   void setCapability(Resource capability);
+  
+  /**
+   * Get the <em>number of running containers</em> on the node.
+   * @return <em>number of running containers</em> on the node
+   */
+  @Public
+  @Stable
   int getNumContainers();
+  
+  @Private
+  @Unstable
   void setNumContainers(int numContainers);
+  
+  /**
+   * Get the <code>NodeHealthStatus</code> of the node. 
+   * @return <code>NodeHealthStatus</code> of the node
+   */
+  @Public
+  @Stable
   NodeHealthStatus getNodeHealthStatus();
+  
+  @Private
+  @Unstable
   void setNodeHealthStatus(NodeHealthStatus nodeHealthStatus);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueACL.java

@@ -18,8 +18,39 @@
 
 package org.apache.hadoop.yarn.api.records;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p><code>QueueACL</code> enumerates the various ACLs for queues.</p>
+ * 
+ * <p>The ACLs are one of:
+ *   <ul>
+ *     <li>{@link #SUBMIT_JOB} - ACL to submit jobs to the queue.</li>
+ *     <li>{@link #ADMINISTER_QUEUE} - ACL to administer the queue.</li>
+ *     <li>{@link #ADMINISTER_JOBS} - ACL to administer jobs in the queue.</li>
+ *   </ul>
+ * </p>
+ * 
+ * @see QueueInfo
+ * @see ClientRMProtocol#getQueueUserAcls(org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest)
+ */
+@Public
+@Stable
 public enum QueueACL {
+  /**
+   * ACL to submit jobs to the queue.
+   */
   SUBMIT_JOB,
+  
+  /**
+   * ACL to administer the queue.
+   */
   ADMINISTER_QUEUE,    
+  
+  /**
+   * ACL to administer jobs in the queue.
+   */
   ADMINISTER_JOBS;            // currently unused
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueInfo.java

@@ -20,25 +20,114 @@ package org.apache.hadoop.yarn.api.records;
 
 import java.util.List;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+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>It includes information such as:
+ *   <ul>
+ *     <li>Queue name.</li>
+ *     <li>Capacity of the queue.</li>
+ *     <li>Maximum capacity of the queue.</li>
+ *     <li>Current capacity of the queue.</li>
+ *     <li>Child queues.</li>
+ *     <li>Running applications.</li>
+ *     <li>{@link QueueState} of the queue.</li>
+ *   </ul>
+ * </p>
+ *
+ * @see QueueState
+ * @see ClientRMProtocol#getQueueInfo(org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest)
+ */
+@Public
+@Stable
 public interface QueueInfo {
+  /**
+   * Get the <em>name</em> of the queue.
+   * @return <em>name</em> of the queue
+   */
+  @Public
+  @Stable
   String getQueueName();
+  
+  @Private
+  @Unstable
   void setQueueName(String queueName);
   
+  /**
+   * Get the <em>configured capacity</em> of the queue.
+   * @return <em>configured capacity</em> of the queue
+   */
+  @Public
+  @Stable
   float getCapacity();
+  
+  @Private
+  @Unstable
   void setCapacity(float capacity);
   
+  /**
+   * Get the <em>maximum capacity</em> of the queue.
+   * @return <em>maximum capacity</em> of the queue
+   */
+  @Public
+  @Stable
   float getMaximumCapacity();
+  
+  @Private
+  @Unstable
   void setMaximumCapacity(float maximumCapacity);
   
+  /**
+   * Get the <em>current capacity</em> of the queue.
+   * @return <em>current capacity</em> of the queue
+   */
+  @Public
+  @Stable
   float getCurrentCapacity();
+  
+  @Private
+  @Unstable
   void setCurrentCapacity(float currentCapacity);
   
+  /**
+   * Get the <em>child queues</em> of the queue.
+   * @return <em>child queues</em> of the queue
+   */
+  @Public
+  @Stable
   List<QueueInfo> getChildQueues();
+  
+  @Private
+  @Unstable
   void setChildQueues(List<QueueInfo> childQueues);
   
+  /**
+   * Get the <em>running applications</em> of the queue.
+   * @return <em>running applications</em> of the queue
+   */
+  @Public
+  @Stable
   List<ApplicationReport> getApplications();
+  
+  @Private
+  @Unstable
   void setApplications(List<ApplicationReport> applications);
   
+  /**
+   * Get the <code>QueueState</code> of the queue.
+   * @return <code>QueueState</code> of the queue
+   */
+  @Public
+  @Stable
   QueueState getQueueState();
+  
+  @Private
+  @Unstable
   void setQueueState(QueueState queueState);
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueState.java

@@ -18,10 +18,33 @@
 
 package org.apache.hadoop.yarn.api.records;
 
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
 /**
- * State of a Queue
+ * <p>State of a Queue.</p>
+ * 
+ * <p>A queue is one of:
+ *   <ul>
+ *     <li>{@link #RUNNING} - normal state.</li> 
+ *     <li>{@link #STOPPED} - not accepting new application submissions.
+ *   </ul>
+ * </p>
+ * 
+ * @see QueueInfo
+ * @see ClientRMProtocol#getQueueInfo(org.apache.hadoop.yarn.api.protocolrecords.GetQueueInfoRequest)
  */
+@Public
+@Stable
 public enum QueueState {
+  /**
+   * Stopped - Not accepting submissions of new applications.
+   */
   STOPPED,
+  
+  /**
+   * Running - normal operation.
+   */
   RUNNING
 }

hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/QueueUserACLInfo.java

@@ -20,10 +20,43 @@ package org.apache.hadoop.yarn.api.records;
 
 import java.util.List;
 
+import org.apache.hadoop.classification.InterfaceAudience.Private;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
+import org.apache.hadoop.classification.InterfaceStability.Stable;
+import org.apache.hadoop.classification.InterfaceStability.Unstable;
+import org.apache.hadoop.yarn.api.ClientRMProtocol;
+
+/**
+ * <p><code>QueueUserACLInfo</code> provides information {@link QueueACL} for
+ * the given user.</p>
+ * 
+ * @see QueueACL
+ * @see ClientRMProtocol#getQueueUserAcls(org.apache.hadoop.yarn.api.protocolrecords.GetQueueUserAclsInfoRequest)
+ */
+@Public
+@Stable
 public interface QueueUserACLInfo {
+  /**
+   * Get the <em>queue name</em> of the queue.
+   * @return <em>queue name</em> of the queue
+   */
+  @Public
+  @Stable
   String getQueueName();
+  
+  @Private
+  @Unstable
   void setQueueName(String queueName);
 
+  /**
+   * Get the list of <code>QueueACL</code> for the given user.
+   * @return list of <code>QueueACL</code> for the given user
+   */
+  @Public
+  @Stable
   List<QueueACL> getUserAcls();
+
+  @Private
+  @Unstable
   void setUserAcls(List<QueueACL> acls);
 }