diff --git a/hadoop-mapreduce-project/CHANGES.txt b/hadoop-mapreduce-project/CHANGES.txt
index 05ffebfdd0..04600ddfd3 100644
--- a/hadoop-mapreduce-project/CHANGES.txt
+++ b/hadoop-mapreduce-project/CHANGES.txt
@@ -1158,6 +1158,8 @@ Release 0.23.0 - Unreleased
     MAPREDUCE-2893. Remove duplicate entry of YarnClientProtocolProvider in
     ClientProtocolProvider services file. (Liang-Chi Hsieh via acmurthy) 
 
+    MAPREDUCE-2891. Javadoc for AMRMProtocol and related records. (acmurthy)
+
 Release 0.22.0 - Unreleased
 
   INCOMPATIBLE CHANGES
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java
index 58dc9e02e4..d194926f94 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/AMRMProtocol.java
@@ -18,16 +18,89 @@
 
 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.AllocateRequest;
 import org.apache.hadoop.yarn.api.protocolrecords.AllocateResponse;
 import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterRequest;
 import org.apache.hadoop.yarn.api.protocolrecords.FinishApplicationMasterResponse;
 import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterRequest;
 import org.apache.hadoop.yarn.api.protocolrecords.RegisterApplicationMasterResponse;
+import org.apache.hadoop.yarn.api.records.Container;
+import org.apache.hadoop.yarn.api.records.ResourceRequest;
 import org.apache.hadoop.yarn.exceptions.YarnRemoteException;
 
+/**
+ * <p>The protocol between a live instance of <code>ApplicationMaster</code> 
+ * and the <code>ResourceManager</code>.</p>
+ * 
+ * <p>This is used by the <code>ApplicationMaster</code> to register/unregister
+ * and to request and obtain resources in the cluster from the
+ * <code>ResourceManager</code>.</p>
+ */
+@Public
+@Stable
 public interface AMRMProtocol {
-  public RegisterApplicationMasterResponse registerApplicationMaster(RegisterApplicationMasterRequest request) throws YarnRemoteException;
-  public FinishApplicationMasterResponse finishApplicationMaster(FinishApplicationMasterRequest request) throws YarnRemoteException;;
-  public AllocateResponse allocate(AllocateRequest request) throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by a new <code>ApplicationMaster</code> to register 
+   * with the <code>ResourceManager</code>.</p> 
+   * 
+   * <p>The <code>ApplicationMaster</code> needs to provide details such
+   * as RPC Port, HTTP tracking url etc. as specified in 
+   * {@link RegisterApplicationMasterRequest}.</p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with critical details such 
+   * as minimum and maximum resource capabilities in the cluster as specified in
+   * {@link RegisterApplicationMasterResponse}.</p>
+   *  
+   * @param request registration request
+   * @return registration respose
+   * @throws YarnRemoteException
+   */
+  public RegisterApplicationMasterResponse registerApplicationMaster(
+      RegisterApplicationMasterRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The interface used by an <code>ApplicationMaster</code> to notify the 
+   * <code>ResourceManager</code> about its completion (success or failed).</p>
+   * 
+   * <p>The <code>ApplicationMaster</code> has to provide details such as 
+   * final state, diagnostics (in case of failures) etc. as specified in 
+   * {@link FinishApplicationMasterRequest}.</p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with 
+   * {@link FinishApplicationMasterResponse}.</p>
+   * 
+   * @param request completion request
+   * @return completion response
+   * @throws YarnRemoteException
+   */
+  public FinishApplicationMasterResponse finishApplicationMaster(
+      FinishApplicationMasterRequest request) 
+  throws YarnRemoteException;
+  
+  /**
+   * <p>The main interface between an <code>ApplicationMaster</code> 
+   * and the <code>ResourceManager</code>.</p>
+   * 
+   * <p>The <code>ApplicationMaster</code> uses this interface to provide a list  
+   * of {@link ResourceRequest} and returns unused {@link Container} allocated 
+   * to it via {@link AllocateRequest}.</p>
+   * 
+   * <p>The <code>ResourceManager</code> responds with list of allocated 
+   * {@link Container}, status of completed containers and headroom information 
+   * for the application.</p> 
+   * 
+   * <p>The <code>ApplicationMaster</code> can use the available headroom 
+   * (resources) to decide how to utilized allocated resources and make 
+   * informed decisions about future resource requests.</p>
+   * 
+   * @param request allocation request
+   * @return allocation response
+   * @throws YarnRemoteException
+   */
+  public AllocateResponse allocate(AllocateRequest request) 
+  throws YarnRemoteException;
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java
index 494cbfd537..2f4d69d14f 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/ClientRMProtocol.java
@@ -40,9 +40,10 @@
 
 public interface ClientRMProtocol {
   public GetNewApplicationIdResponse getNewApplicationId(GetNewApplicationIdRequest request) throws YarnRemoteException;
-  public GetApplicationReportResponse getApplicationReport(GetApplicationReportRequest request) throws YarnRemoteException;
   public SubmitApplicationResponse submitApplication(SubmitApplicationRequest request) throws YarnRemoteException;
   public FinishApplicationResponse finishApplication(FinishApplicationRequest request) throws YarnRemoteException;
+
+  public GetApplicationReportResponse getApplicationReport(GetApplicationReportRequest request) throws YarnRemoteException;
   public GetClusterMetricsResponse getClusterMetrics(GetClusterMetricsRequest request) throws YarnRemoteException;
   public GetAllApplicationsResponse getAllApplications(GetAllApplicationsRequest request) throws YarnRemoteException;
   public GetClusterNodesResponse getClusterNodes(GetClusterNodesRequest request) throws YarnRemoteException;
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java
index 2b410be85e..10448b19a2 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateRequest.java
@@ -20,36 +20,150 @@
 
 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.AMRMProtocol;
 import org.apache.hadoop.yarn.api.records.ApplicationAttemptId;
+import org.apache.hadoop.yarn.api.records.Container;
 import org.apache.hadoop.yarn.api.records.ContainerId;
 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
+ * {@link AMRMProtocol#allocate(AllocateRequest)}.</p> 
+ *
+ * <p>The request includes:
+ *   <ul>
+ *     <li>
+ *         {@link ApplicationAttemptId} being managed by the 
+ *         <code>ApplicationMaster</code>
+ *     </li>
+ *     <li>A response id to track duplicate responses.</li>
+ *     <li>Progress information.</li>
+ *     <li>
+ *       A list of {@link ResourceRequest} to inform the 
+ *       <code>ResourceManager</code> about the application's 
+ *       resource requirements.
+ *     </li>
+ *     <li>
+ *       A list of unused {@link Container} which are being returned. 
+ *     </li>
+ *     <li></li>
+ *   </ul>
+ * </p>
+ * 
+ */
+@Public
+@Stable
 public interface AllocateRequest {
 
+  /**
+   * Get the {@link ApplicationAttemptId} being managed by the 
+   * <code>ApplicationMaster</code>.
+   * @return <code>ApplicationAttemptId</code> being managed by the 
+   *         <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   ApplicationAttemptId getApplicationAttemptId();
+  
+  @Private
+  @Unstable
   void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
 
+  /**
+   * Get the response id.
+   * @return the response id
+   */
+  @Public
+  @Stable
   int getResponseId();
+  
+  @Private
+  @Unstable
   void setResponseId(int id);
 
+  /**
+   * Get the current progress of application. 
+   * @return the current progress of application
+   */
+  @Public
+  @Stable
   float getProgress();
+  
+  @Private
+  @Unstable
   void setProgress(float progress);
 
+  /**
+   * Get the list of <code>ResourceRequest</code> to upate the 
+   * <code>ResourceManager</code> about the application's resource requirements.
+   * @return the list of <code>ResourceRequest</code>
+   */
+  @Public
+  @Stable
   List<ResourceRequest> getAskList();
+  
+  @Private
+  @Unstable
   ResourceRequest getAsk(int index);
+  
+  @Private
+  @Unstable
   int getAskCount();
   
+  /**
+   * Get the list of <code>ContainerId</code> of unused containers being 
+   * released by the <code>ApplicationMaster</code>.
+   * @return list of <code>ContainerId</code> of unused containers being 
+   *         released by the <code>ApplicationMaster</code> 
+   */
+  @Public
+  @Stable
   List<ContainerId> getReleaseList();
+  
+  @Private
+  @Unstable
   ContainerId getRelease(int index);
+  
+  @Private
+  @Unstable
   int getReleaseCount();
 
+  
+  @Private
+  @Unstable
   void addAllAsks(List<ResourceRequest> resourceRequest);
+  
+  @Private
+  @Unstable
   void addAsk(ResourceRequest request);
+  
+  @Private
+  @Unstable
   void removeAsk(int index);
+  
+  @Private
+  @Unstable
   void clearAsks();
   
+  
+  @Private
+  @Unstable
   void addAllReleases(List<ContainerId> releaseContainers);
+  
+  @Private
+  @Unstable
   void addRelease(ContainerId container);
+  
+  @Private
+  @Unstable
   void removeRelease(int index);
+  
+  @Private
+  @Unstable
   void clearReleases();
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java
index 00409c50a5..0d7140223b 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/AllocateResponse.java
@@ -18,10 +18,46 @@
 
 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.AMResponse;
+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
+ * {@link AMRMProtocol#allocate(AllocateRequest)}.</p>
+ *
+ * <p>The response, via {@link AMResponse}, includes:
+ *   <ul>
+ *     <li>Response ID to track duplicate responses.</li>
+ *     <li>
+ *       A reboot flag to let the <code>ApplicationMaster</code> that its 
+ *       horribly out of sync and needs to reboot.</li>
+ *     <li>A list of newly allocated {@link Container}.</li>
+ *     <li>A list of completed {@link Container}.</li>
+ *     <li>
+ *       The available headroom for resources in the cluster for the
+ *       application. 
+ *     </li>
+ *   </ul>
+ * </p>
+ */
+@Public
+@Stable
 public interface AllocateResponse {
+  /**
+   * Get the {@link AMResponse} sent by the <code>ResourceManager</code>.
+   * @return <code>AMResponse</code> sent by the <code>ResourceManager</code>
+   */
+  @Public
+  @Stable
   public abstract AMResponse getAMResponse();
-  
+
+  @Private
+  @Unstable
   public abstract void setAMResponse(AMResponse amResponse);
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterRequest.java
index fbb71e753a..d9baf4b148 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterRequest.java
@@ -18,21 +18,85 @@
 
 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
+ * {@link AMRMProtocol#finishApplicationMaster(FinishApplicationMasterRequest)}
+ * api.</p>
+ * 
+ * <p>The final request includes details such:
+ *   <ul>
+ *     <li>
+ *         {@link ApplicationAttemptId} being managed by the 
+ *         <code>ApplicationMaster</code>
+ *     </li>
+ *     <li>Final state of the <code>ApplicationMaster</code></li>
+ *     <li>
+ *       Diagnostic information in case of failure of the
+ *       <code>ApplicationMaster</code>
+ *     </li>
+ *     <li>Tracking URL</li>
+ *   </ul>
+ * </p>
+ *
+ */
 public interface FinishApplicationMasterRequest {
 
+  /**
+   * Get the {@link ApplicationAttemptId} being managed by the 
+   * <code>ApplicationMaster</code>.
+   * @return <code>ApplicationAttemptId</code> being managed by the 
+   *         <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   ApplicationAttemptId getApplicationAttemptId();
+  
+  @Private
+  @Unstable
   void setAppAttemptId(ApplicationAttemptId applicationAttemptId);
 
+  /**
+   * Get final state of the <code>ApplicationMaster</code>.
+   * @return final state of the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   String getFinalState();
+  
+  @Private
+  @Unstable
   void setFinalState(String string);
 
+  /**
+   * Get diagnostic information if the application failed.
+   * @return diagnostic information if the application failed
+   */
+  @Public
+  @Stable
   String getDiagnostics();
+  
+  @Private
+  @Unstable
   void setDiagnostics(String string);
 
+  /**
+   * Get the tracking URL for the <code>ApplicationMaster</code>.
+   * @return the tracking URL for the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   String getTrackingUrl();
+  
+  @Private
+  @Unstable
   void setTrackingUrl(String historyUrl);
 
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterResponse.java
index 1c30ac4a65..45682bf5dc 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/FinishApplicationMasterResponse.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.AMRMProtocol;
+
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to a 
+ * <code>ApplicationMaster</code> on it's completion via the
+ * {@link AMRMProtocol#finishApplicationMaster(FinishApplicationMasterRequest)}
+ * api.</p>
+ * 
+ * <p>Currently, this is empty.</p>
+ */
+@Public
+@Stable
 public interface FinishApplicationMasterResponse {
 
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterRequest.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterRequest.java
index 202dca7af9..2325b5ad0d 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterRequest.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterRequest.java
@@ -18,19 +18,83 @@
 
 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 request sent by the <code>ApplicationMaster</code> to 
+ * <code>ResourceManager</code> on registration via the 
+ * {@link AMRMProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)} 
+ * api.</p>
+ * 
+ * <p>The registration includes details such as:
+ *   <ul>
+ *     <li>
+ *         {@link ApplicationAttemptId} being managed by the 
+ *         <code>ApplicationMaster</code>
+ *     </li>
+ *     <li>Hostname on which the AM is running.</li>
+ *     <li>RPC Port</li>
+ *     <li>Tracking URL</li>
+ *   </ul>
+ * </p>
+ */
+@Public
+@Stable
 public interface RegisterApplicationMasterRequest {
 
+  /**
+   * Get the {@link ApplicationAttemptId} being managed by the 
+   * <code>ApplicationMaster</code>.
+   * @return <code>ApplicationAttemptId</code> being managed by the 
+   *         <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   ApplicationAttemptId getApplicationAttemptId();
+  
+  @Private
+  @Unstable
   void setApplicationAttemptId(ApplicationAttemptId applicationAttemptId);
 
+  /**
+   * Get the host on which the <code>ApplicationMaster</code> is running.
+   * @return host on which the <code>ApplicationMaster</code> is running
+   */
+  @Public
+  @Stable
   String getHost();
+  
+  @Private
+  @Unstable
   void setHost(String host);
 
+  /**
+   * Get the RPC port on which the <code>ApplicationMaster</code> is responding. 
+   * @return the RPC port on which the <code>ApplicationMaster</code> is 
+   *         responding
+   */
+  @Public
+  @Stable
   int getRpcPort();
+  
+  @Private
+  @Unstable
   void setRpcPort(int port);
 
+  /**
+   * Get the tracking URL for the <code>ApplicationMaster</code>.
+   * @return the tracking URL for the <code>ApplicationMaster</code>
+   */
+  @Public
+  @Stable
   String getTrackingUrl();
+  
+  @Private
+  @Unstable
   void setTrackingUrl(String string);
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterResponse.java
index 9d595cf382..b2232b8d7c 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/RegisterApplicationMasterResponse.java
@@ -18,11 +18,53 @@
 
 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.Resource;
 
+/**
+ * <p>The response sent by the <code>ResourceManager</code> to a new 
+ * <code>ApplicationMaster</code> on registration via the 
+ * {@link AMRMProtocol#registerApplicationMaster(RegisterApplicationMasterRequest)} 
+ * api.</p>
+ * 
+ * <p>The response contains critical details such as:
+ * <ul>
+ *   <li>Minimum capability for allocated resources in the cluster.</li>
+ *   <li>Maximum capability for allocated resources in the cluster.</li>
+ * </ul>
+ * </p>
+ */
+@Public
+@Stable
 public interface RegisterApplicationMasterResponse {
+  
+  /**
+   * Get the minimum capability for any {@link Resource} allocated by the 
+   * <code>ResourceManager</code> in the cluster.
+   * @return minimum capability of allocated resources in the cluster
+   */
+  @Public
+  @Stable
   public Resource getMinimumResourceCapability();
+  
+  @Private
+  @Unstable
   public void setMinimumResourceCapability(Resource capability);
+  
+  /**
+   * Get the maximum capability for any {@link Resource} allocated by the 
+   * <code>ResourceManager</code> in the cluster.
+   * @return maximum capability of allocated resources in the cluster
+   */
+  @Public
+  @Stable
   public Resource getMaximumResourceCapability();
+  
+  @Private
+  @Unstable
   public void setMaximumResourceCapability(Resource capability);
 }
diff --git a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java
index a14b641f68..33d3b92968 100644
--- a/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java
+++ b/hadoop-mapreduce-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/AMResponse.java
@@ -20,31 +20,139 @@
 
 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.AMRMProtocol;
+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
+ * {@link AMRMProtocol#allocate(AllocateRequest)}.</p>
+ *
+ * <p>The response includes:
+ *   <ul>
+ *     <li>Response ID to track duplicate responses.</li>
+ *     <li>
+ *       A reboot flag to let the <code>ApplicationMaster</code> that its 
+ *       horribly out of sync and needs to reboot.</li>
+ *     <li>A list of newly allocated {@link Container}.</li>
+ *     <li>A list of completed {@link Container}.</li>
+ *     <li>
+ *       The available headroom for resources in the cluster for the
+ *       application. 
+ *     </li>
+ *   </ul>
+ * </p>
+ */
+@Public
+@Unstable
 public interface AMResponse {
+  /**
+   * Should the <code>ApplicationMaster</code> reboot for being horribly 
+   * out-of-sync with the <code>ResourceManager</code> as deigned by 
+   * {@link #getResponseId()}?
+   * 
+   * @return <code>true</code> if the <code>ApplicationMaster</code> should
+   *         reboot, <code>false</code> otherwise
+   */
+  @Public
+  @Stable
   public boolean getReboot();
+  
+  @Private
+  @Unstable
+  public void setReboot(boolean reboot);
+
+  /**
+   * Get the last response id.
+   * @return the last response id
+   */
+  @Public
+  @Stable
   public int getResponseId();
   
+  @Private
+  @Unstable
+  public void setResponseId(int responseId);
+
+  /**
+   * Get the list of newly allocated {@link Container} by the 
+   * <code>ResourceManager</code>.
+   * @return list of newly allocated <code>Container</code> 
+   */
+  @Public
+  @Stable
   public List<Container> getNewContainerList();
+
+  @Private
+  @Unstable
   public Container getNewContainer(int index);
+
+  @Private
+  @Unstable
   public int getNewContainerCount();
 
-  public void setReboot(boolean reboot);
-  public void setResponseId(int responseId);
-  
+  @Private
+  @Unstable
   public void addAllNewContainers(List<Container> containers);
+
+  @Private
+  @Unstable
   public void addNewContainer(Container container);
+
+  @Private
+  @Unstable
   public void removeNewContainer(int index);
+
+  @Private
+  @Unstable
   public void clearNewContainers();
   
-  public void setAvailableResources(Resource limit);
+  /**
+   * Get available headroom for resources in the cluster for the application.
+   * @param limit available headroom for resources in the cluster for the application
+   */
+  @Public
+  @Stable
   public Resource getAvailableResources();
 
+  @Private
+  @Unstable
+  public void setAvailableResources(Resource limit);
+  
+  /**
+   * Get the list of completed containers.
+   * @return the list of completed containers
+   */
+  @Public
+  @Stable
   public List<Container> getFinishedContainerList();
+
+  @Private
+  @Unstable
   public Container getFinishedContainer(int index);
+
+  @Private
+  @Unstable
   public int getFinishedContainerCount();
   
+
+  @Private
+  @Unstable
   public void addAllFinishedContainers(List<Container> containers);
+
+  @Private
+  @Unstable
   public void addFinishedContainer(Container container);
+
+  @Private
+  @Unstable
   public void removeFinishedContainer(int index);
+
+  @Private
+  @Unstable
   public void clearFinishedContainers();
 }
\ No newline at end of file