YARN-11380. Fix hadoop-yarn-api module Java Doc Errors. (#5152). Contributed by Shilun Fan.

Signed-off-by: Ayush Saxena <ayushsaxena@apache.org>

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

@@ -94,8 +94,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          request for an application report
    * @return application report
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -126,8 +126,8 @@ public interface ApplicationBaseProtocol {
    *          request for report on applications
    * @return report on applications matching the given application types defined
    *         in the request
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @see GetApplicationsRequest
    */
   @Public
@@ -166,8 +166,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          request for an application attempt report
    * @return application attempt report
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -199,8 +199,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          request for reports on all application attempts of an application
    * @return reports on all application attempts of an application
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -234,8 +234,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          request for a container report
    * @return container report
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -271,8 +271,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          request for a list of container reports of an application attempt.
    * @return reports on all containers of an application attempt
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -293,8 +293,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          request to get a delegation token for the client.
    * @return delegation token that can be used to talk to this service
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -308,8 +308,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          the delegation token to be renewed.
    * @return the new expiry time for the delegation token.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Private
   @Unstable
@@ -323,8 +323,8 @@ public interface ApplicationBaseProtocol {
    * @param request
    *          the delegation token to be cancelled.
    * @return an empty response.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Private
   @Unstable

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

@@ -112,8 +112,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @param request request to get a new <code>ApplicationId</code>
    * @return response containing the new <code>ApplicationId</code> to be used
    * to submit an application
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @see #submitApplication(SubmitApplicationRequest)
    */
   @Public
@@ -157,8 +157,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * 
    * @param request request to submit a new application
    * @return (empty) response on accepting the submission
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @see #getNewApplication(GetNewApplicationRequest)
    */
   @Public
@@ -184,8 +184,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @param request request to fail an attempt
    * @return <code>ResourceManager</code> returns an empty response
    *         on success and throws an exception on rejecting the request
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest)
    */
   @Public
@@ -210,8 +210,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @param request request to abort a submitted application
    * @return <code>ResourceManager</code> returns an empty response
    *         on success and throws an exception on rejecting the request
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @see #getQueueUserAcls(GetQueueUserAclsInfoRequest) 
    */
   @Public
@@ -232,8 +232,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * 
    * @param request request for cluster metrics
    * @return cluster metrics
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -252,8 +252,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * 
    * @param request request for report on all nodes
    * @return report on all nodes
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -274,8 +274,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * 
    * @param request request to get queue information
    * @return queue information
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -294,8 +294,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * 
    * @param request request to get queue acls for <em>current user</em>
    * @return queue acls for <em>current user</em>
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -309,8 +309,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * 
    * @param request the application ID and the target queue
    * @return an empty response
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -383,7 +383,7 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @return response the {@link ReservationId} on accepting the submission
    * @throws YarnException if the request is invalid or reservation cannot be
    *           created successfully
-   * @throws IOException
+   * @throws IOException io error occur.
    * 
    */
   @Public
@@ -417,7 +417,7 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @return response empty on successfully updating the existing reservation
    * @throws YarnException if the request is invalid or reservation cannot be
    *           updated successfully
-   * @throws IOException
+   * @throws IOException io error occur.
    * 
    */
   @Public
@@ -439,7 +439,7 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @return response empty on successfully deleting the existing reservation
    * @throws YarnException if the request is invalid or reservation cannot be
    *           deleted successfully
-   * @throws IOException
+   * @throws IOException io error occur.
    *
    */
   @Public
@@ -494,13 +494,13 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
 
   /**
    * <p>
-   * The interface used by client to get node to labels mappings in existing cluster
+   * The interface used by client to get node to labels mappings in existing cluster.
    * </p>
    *
-   * @param request
+   * @param request get node to labels request.
    * @return node to labels mappings
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -510,13 +510,13 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
   /**
    * <p>
    * The interface used by client to get labels to nodes mappings
-   * in existing cluster
+   * in existing cluster.
    * </p>
    *
-   * @param request
+   * @param request get label to nodes request.
    * @return labels to nodes mappings
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -530,8 +530,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    *
    * @param request to get node labels collection of this cluster
    * @return node labels collection of this cluster
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -544,8 +544,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * </p>
    * @param request to set priority of an application
    * @return an empty response
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -573,8 +573,8 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @param request request to signal a container
    * @return <code>ResourceManager</code> returns an empty response
    *         on success and throws an exception on rejecting the request
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable
@@ -691,7 +691,7 @@ public interface ApplicationClientProtocol extends ApplicationBaseProtocol {
    * @param request request to get nodes to attributes mapping.
    * @return nodes to attributes mappings.
    * @throws YarnException if any error happens inside YARN.
-   * @throws IOException
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable

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

@@ -76,9 +76,9 @@ public interface ApplicationMasterProtocol {
    * </p>
    *
    * @param request registration request
-   * @return registration respose
-   * @throws YarnException
-   * @throws IOException
+   * @return registration response
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @throws InvalidApplicationMasterRequestException The exception is thrown
    *           when an ApplicationMaster tries to register more then once.
    * @see RegisterApplicationMasterRequest
@@ -104,8 +104,8 @@ public interface ApplicationMasterProtocol {
    * 
    * @param request completion request
    * @return completion response
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @see FinishApplicationMasterRequest
    * @see FinishApplicationMasterResponse
    */
@@ -154,8 +154,8 @@ public interface ApplicationMasterProtocol {
    * @param request
    *          allocation request
    * @return allocation response
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    * @throws InvalidApplicationMasterRequestException
    *           This exception is thrown when an ApplicationMaster calls allocate
    *           without registering first.

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

@@ -55,8 +55,8 @@ public interface ClientSCMProtocol {
    *
    * @param request request to claim a resource in the shared cache
    * @return response indicating if the resource is already in the cache
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   public UseSharedCacheResourceResponse use(
       UseSharedCacheResourceRequest request) throws YarnException, IOException;
@@ -81,8 +81,8 @@ public interface ClientSCMProtocol {
    *
    * @param request request to release a resource in the shared cache
    * @return (empty) response on releasing the resource
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   public ReleaseSharedCacheResourceResponse release(
       ReleaseSharedCacheResourceRequest request) throws YarnException, IOException;

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

@@ -102,8 +102,8 @@ public interface ContainerManagementProtocol {
    * @return response including conatinerIds of all successfully launched
    *         containers, a containerId-to-exception map for failed requests and
    *         a allServicesMetaData map.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -138,8 +138,8 @@ public interface ContainerManagementProtocol {
    * @return response which includes a list of containerIds of successfully
    *         stopped containers, a containerId-to-exception map for failed
    *         requests.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -174,8 +174,8 @@ public interface ContainerManagementProtocol {
    *         successfully queried containers and a containerId-to-exception map
    *         for failed requests.
    * 
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Stable
@@ -195,8 +195,8 @@ public interface ContainerManagementProtocol {
    *         whose resource has been successfully increased and a
    *         containerId-to-exception map for failed requests.
    *
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable

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

@@ -36,7 +36,7 @@ public interface CsiAdaptorPlugin extends CsiAdaptorProtocol {
    * customized configuration from yarn-site.xml.
    * @param driverName the name of the csi-driver.
    * @param conf configuration.
-   * @throws YarnException
+   * @throws YarnException exceptions from yarn servers.
    */
   void init(String driverName, Configuration conf) throws YarnException;
 

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

@@ -39,8 +39,8 @@ public interface CsiAdaptorProtocol {
    * the name of the driver and its version.
    * @param request get plugin info request.
    * @return response that contains driver name and its version.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   GetPluginInfoResponse getPluginInfo(GetPluginInfoRequest request)
       throws YarnException, IOException;
@@ -51,8 +51,8 @@ public interface CsiAdaptorProtocol {
    * or not, with a detailed message.
    * @param request validate volume capability request.
    * @return validation response.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   ValidateVolumeCapabilitiesResponse validateVolumeCapacity(
       ValidateVolumeCapabilitiesRequest request) throws YarnException,
@@ -63,8 +63,8 @@ public interface CsiAdaptorProtocol {
    * to the local file system and become visible for clients.
    * @param request publish volume request.
    * @return publish volume response.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   NodePublishVolumeResponse nodePublishVolume(
       NodePublishVolumeRequest request) throws YarnException, IOException;
@@ -75,8 +75,8 @@ public interface CsiAdaptorProtocol {
    * volume from given node.
    * @param request un-publish volume request.
    * @return un-publish volume response.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   NodeUnpublishVolumeResponse nodeUnpublishVolume(
       NodeUnpublishVolumeRequest request) throws YarnException, IOException;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Public
+@Public
 package org.apache.hadoop.yarn.api;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
 

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

@@ -137,6 +137,7 @@ public abstract class GetApplicationsRequest {
    *
    *
    * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
+   * @param applicationTypes application types.
    * @return a report of Applications in {@link GetApplicationsRequest}
    */
   @Public
@@ -158,6 +159,7 @@ public abstract class GetApplicationsRequest {
    *
    *
    * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
+   * @param applicationStates application states.
    * @return  a report of Applications in {@link GetApplicationsRequest}
    */
   @Public
@@ -173,12 +175,14 @@ public abstract class GetApplicationsRequest {
   /**
    * <p>
    * The request from clients to get a report of Applications matching the
-   * giving and application types and application types in the cluster from the
+   * giving and application types and application states in the cluster from the
    * <code>ResourceManager</code>.
    * </p>
    *
    *
    * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
+   * @param applicationStates application states.
+   * @param applicationTypes application types.
    * @return  a report of Applications in <code>GetApplicationsRequest</code>
    */
   @Public
@@ -309,20 +313,20 @@ public abstract class GetApplicationsRequest {
   public abstract Range<Long> getStartRange();
 
   /**
-   * Set the range of start times to filter applications on
+   * Set the range of start times to filter applications.
    *
-   * @param range
+   * @param range range of start times.
    */
   @Private
   @Unstable
   public abstract void setStartRange(Range<Long> range);
 
   /**
-   * Set the range of start times to filter applications on
+   * Set the range of start times to filter applications.
    *
    * @param begin beginning of the range
    * @param end end of the range
-   * @throws IllegalArgumentException
+   * @throws IllegalArgumentException if an argument is invalid.
    */
   @Private
   @Unstable
@@ -330,7 +334,7 @@ public abstract class GetApplicationsRequest {
       throws IllegalArgumentException;
 
   /**
-   * Get the range of finish times to filter applications on
+   * Get the range of finish times to filter applications.
    *
    * @return {@link Range} of finish times to filter applications on
    */
@@ -339,38 +343,38 @@ public abstract class GetApplicationsRequest {
   public abstract Range<Long> getFinishRange();
 
   /**
-   * Set the range of finish times to filter applications on
+   * Set the range of finish times to filter applications.
    *
-   * @param range
+   * @param range range of finish times.
    */
   @Private
   @Unstable
   public abstract void setFinishRange(Range<Long> range);
 
   /**
-   * Set the range of finish times to filter applications on
+   * Set the range of finish times to filter applications.
    *
    * @param begin beginning of the range
    * @param end end of the range
-   * @throws IllegalArgumentException
+   * @throws IllegalArgumentException if an argument is invalid.
    */
   @Private
   @Unstable
   public abstract void setFinishRange(long begin, long end);
 
   /**
-   * Get the tags to filter applications on
+   * Get the tags to filter applications.
    *
-   * @return list of tags to filter on
+   * @return list of tags to filter.
    */
   @Private
   @Unstable
   public abstract Set<String> getApplicationTags();
 
   /**
-   * Set the list of tags to filter applications on
+   * Set the list of tags to filter applications.
    *
-   * @param tags list of tags to filter on
+   * @param tags list of tags to filter.
    */
   @Private
   @Unstable

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

@@ -42,7 +42,7 @@ public abstract class GetClusterNodeAttributesResponse {
   /**
    * Create instance of GetClusterNodeAttributesResponse.
    *
-   * @param attributes
+   * @param attributes Map of Node attributeKey to Type.
    * @return GetClusterNodeAttributesResponse.
    */
   public static GetClusterNodeAttributesResponse newInstance(

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

@@ -65,6 +65,7 @@ public abstract class GetContainerStatusesResponse {
 
   /**
    * Set the <code>ContainerStatus</code>es of the requested containers.
+   * @param statuses <code>ContainerStatus</code>es of the requested containers.
    */
   @Private
   @Unstable
@@ -72,7 +73,7 @@ public abstract class GetContainerStatusesResponse {
 
   /**
    * Get the containerId-to-exception map in which the exception indicates error
-   * from per container for failed requests
+   * from per container for failed requests.
    * @return map of containerId-to-exception
    */
   @Public
@@ -81,7 +82,9 @@ public abstract class GetContainerStatusesResponse {
 
   /**
    * Set the containerId-to-exception map in which the exception indicates error
-   * from per container for failed requests
+   * from per container for failed requests.
+   *
+   * @param failedContainers containerId-to-exception map.
    */
   @Private
   @Unstable

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

@@ -80,6 +80,8 @@ public abstract class GetLocalizationStatusesResponse {
   /**
    * Set the containerId-to-exception map in which the exception indicates error
    * from per container for failed request.
+   *
+   * @param failedContainers containerId-to-exception map.
    */
   @InterfaceAudience.Private
   public abstract void setFailedRequests(

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

@@ -48,7 +48,7 @@ public abstract class GetNodesToAttributesRequest {
   /**
    * Set hostnames for which mapping is required.
    *
-   * @param hostnames
+   * @param hostnames Set of hostnames.
    */
   @InterfaceAudience.Public
   @InterfaceStability.Evolving

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

@@ -68,6 +68,9 @@ public abstract class IncreaseContainersResourceResponse {
   /**
    * Set the list of containerIds of containers whose resource have
    * been successfully increased.
+   *
+   * @param succeedIncreasedContainers list of containerIds of containers whose resource have
+   * been successfully increased.
    */
   @Private
   @Unstable
@@ -86,6 +89,8 @@ public abstract class IncreaseContainersResourceResponse {
   /**
    * Set the containerId-to-exception map in which the exception indicates
    * error from each container for failed requests.
+   *
+   * @param failedRequests map of containerId-to-exception.
    */
   @Private
   @Unstable

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

@@ -66,6 +66,8 @@ public abstract class KillApplicationResponse {
 
   /**
    * Set the flag which indicates that the process of killing application is completed or not.
+   * @param isKillCompleted true if the process of killing application has completed,
+   *     false otherwise.
    */
   @Private
   @Unstable

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

@@ -53,6 +53,9 @@ public abstract class RegisterApplicationMasterRequest {
    *  <li>trackingUrl: null</li>
    * </ul>
    * The port is allowed to be any integer larger than or equal to -1.
+   * @param host host on which the ApplicationMaster is running.
+   * @param port the RPC port  on which the ApplicationMaster is responding.
+   * @param trackingUrl tracking URL for the ApplicationMaster.
    * @return the new instance of <code>RegisterApplicationMasterRequest</code>
    */
   @Public

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

@@ -94,7 +94,7 @@ public abstract class RegisterApplicationMasterResponse {
 
   /**
    * Set the <code>ApplicationACL</code>s for the application. 
-   * @param acls
+   * @param acls ApplicationACLs for the application.
    */
   @Private
   @Unstable
@@ -113,6 +113,8 @@ public abstract class RegisterApplicationMasterResponse {
 
   /**
    * Set ClientToAMToken master key.
+   *
+   * @param key ClientToAMToken master key.
    */
   @Public
   @Stable
@@ -127,7 +129,8 @@ public abstract class RegisterApplicationMasterResponse {
   public abstract String getQueue();
   
   /**
-   * <p>Set the queue that the application was placed in.<p>
+   * <p>Set the queue that the application was placed in.</p>
+   * @param queue queue.
    */
   @Public
   @Stable

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

@@ -56,6 +56,7 @@ public abstract class SignalContainerRequest {
 
   /**
    * Set the <code>ContainerId</code> of the container to signal.
+   * @param containerId containerId.
    */
   @Public
   @Unstable
@@ -71,6 +72,7 @@ public abstract class SignalContainerRequest {
 
   /**
    * Set the <code>SignalContainerCommand</code> of the signal request.
+   * @param command signal container command.
    */
   @Public
   @Unstable

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

@@ -86,7 +86,8 @@ public abstract class StartContainersResponse {
 
   /**
    * Set the containerId-to-exception map in which the exception indicates error
-   * from per container for failed requests
+   * from per container for failed requests.
+   * @param failedContainers container for failed requests.
    */
   @Private
   @Unstable

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

@@ -65,6 +65,7 @@ public abstract class StopContainersResponse {
 
   /**
    * Set the list of containerIds of successfully stopped containers.
+   * @param succeededRequests the list of containerIds of successfully stopped containers.
    */
   @Private
   @Unstable
@@ -73,8 +74,8 @@ public abstract class StopContainersResponse {
 
   /**
    * Get the containerId-to-exception map in which the exception indicates error
-   * from per container for failed requests
-   * @return map of containerId-to-exception
+   * from per container for failed requests.
+   * @return map of containerId-to-exception.
    */
   @Public
   @Stable
@@ -82,7 +83,8 @@ public abstract class StopContainersResponse {
 
   /**
    * Set the containerId-to-exception map in which the exception indicates error
-   * from per container for failed requests
+   * from per container for failed requests.
+   * @param failedRequests map of containerId-to-exception.
    */
   @Private
   @Unstable

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/protocolrecords/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Public
+@Public
 package org.apache.hadoop.yarn.api.protocolrecords;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
 

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

@@ -516,7 +516,7 @@ public abstract class ApplicationSubmissionContext {
       List<ResourceRequest> requests);
 
   /**
-   * Get the attemptFailuresValidityInterval in milliseconds for the application
+   * Get the attemptFailuresValidityInterval in milliseconds for the application.
    *
    * @return the attemptFailuresValidityInterval
    */
@@ -525,8 +525,8 @@ public abstract class ApplicationSubmissionContext {
   public abstract long getAttemptFailuresValidityInterval();
 
   /**
-   * Set the attemptFailuresValidityInterval in milliseconds for the application
-   * @param attemptFailuresValidityInterval
+   * Set the attemptFailuresValidityInterval in milliseconds for the application.
+   * @param attemptFailuresValidityInterval attempt failures validity interval.
    */
   @Public
   @Stable

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

@@ -59,7 +59,7 @@ public abstract class LocalizationStatus {
 
   /**
    * Sets the resource key.
-   * @param resourceKey
+   * @param resourceKey resource key.
    */
   @InterfaceAudience.Private
   public abstract void setResourceKey(String resourceKey);

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

@@ -157,7 +157,7 @@ public abstract class LogAggregationContext {
    * Set include pattern. This includePattern only takes affect
    * on logs that exist at the time of application finish.
    *
-   * @param includePattern
+   * @param includePattern include pattern.
    */
   @Public
   @Unstable
@@ -177,7 +177,7 @@ public abstract class LogAggregationContext {
    * Set exclude pattern. This excludePattern only takes affect
    * on logs that exist at the time of application finish.
    *
-   * @param excludePattern
+   * @param excludePattern exclude pattern.
    */
   @Public
   @Unstable
@@ -195,7 +195,9 @@ public abstract class LogAggregationContext {
   /**
    * Set include pattern in a rolling fashion.
    * 
-   * @param rolledLogsIncludePattern
+   * @param rolledLogsIncludePattern It uses Java Regex to filter the log files
+   * which match the defined include pattern and those log files
+   * will be aggregated in a rolling fashion.
    */
   @Public
   @Unstable
@@ -214,7 +216,7 @@ public abstract class LogAggregationContext {
   /**
    * Set exclude pattern for in a rolling fashion.
    * 
-   * @param rolledLogsExcludePattern
+   * @param rolledLogsExcludePattern rolled logs exclude pattern.
    */
   @Public
   @Unstable
@@ -233,7 +235,7 @@ public abstract class LogAggregationContext {
   /**
    * Set the log aggregation policy class.
    *
-   * @param className
+   * @param className log aggregation policy class name.
    */
   @Public
   @Unstable
@@ -255,7 +257,7 @@ public abstract class LogAggregationContext {
    * It is up to the log aggregation policy class to decide how to parse
    * the parameters string.
    *
-   * @param parameters
+   * @param parameters log aggregation policy parameters.
    */
   @Public
   @Unstable

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

@@ -243,6 +243,7 @@ public abstract class NodeReport {
 
   /**
    * Set the decommissioning timeout in seconds (null indicates absent timeout).
+   * @param decommissioningTimeout decommissioning time out.
    * */
   public void setDecommissioningTimeout(Integer decommissioningTimeout) {}
 
@@ -256,7 +257,8 @@ public abstract class NodeReport {
 
   /**
    * Set the node update type (null indicates absent node update type).
-   * */
+   * @param nodeUpdateType node update type.
+   */
   public void setNodeUpdateType(NodeUpdateType nodeUpdateType) {}
 
   /**

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

@@ -251,6 +251,7 @@ public abstract class QueueInfo {
   
   /**
    * Set the <code>accessible node labels</code> of the queue.
+   * @param labels node label expression of the queue.
    */
   @Private
   @Unstable

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

@@ -437,17 +437,17 @@ public abstract class ResourceRequest implements Comparable<ResourceRequest> {
 
   /**
    * <p>For a request at a network hierarchy level, set whether locality can be relaxed
-   * to that level and beyond.<p>
+   * to that level and beyond.</p>
    * 
    * <p>If the flag is off on a rack-level <code>ResourceRequest</code>,
    * containers at that request's priority will not be assigned to nodes on that
    * request's rack unless requests specifically for those nodes have also been
-   * submitted.<p>
+   * submitted.</p>
    * 
    * <p>If the flag is off on an {@link ResourceRequest#ANY}-level
    * <code>ResourceRequest</code>, containers at that request's priority will
    * only be assigned on racks for which specific requests have also been
-   * submitted.<p>
+   * submitted.</p>
    * 
    * <p>For example, to request a container strictly on a specific node, the
    * corresponding rack-level and any-level requests should have locality

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

@@ -38,6 +38,8 @@ public abstract class SerializedException {
   /**
    * Constructs a new <code>SerializedException</code> with the specified detail
    * message and cause.
+   * @param message exception detail message.
+   * @param cause cause of the exception.
    */
   @Private
   @Unstable
@@ -46,6 +48,7 @@ public abstract class SerializedException {
   /**
    * Constructs a new <code>SerializedException</code> with the specified detail
    * message.
+   * @param message exception detail message.
    */
   @Private
   @Unstable
@@ -53,6 +56,7 @@ public abstract class SerializedException {
 
   /**
    * Constructs a new <code>SerializedException</code> with the specified cause.
+   * @param cause cause of the exception.
    */
   @Private
   @Unstable

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/api/records/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Public
+@Public
 package org.apache.hadoop.yarn.api.records;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
 

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/conf/ConfigurationProvider.java

@@ -44,12 +44,12 @@ public abstract class ConfigurationProvider {
   }
 
   /**
-   * Opens an InputStream at the indicated file
-   * @param bootstrapConf Configuration
-   * @param name The configuration file name
+   * Opens an InputStream at the indicated file.
+   * @param bootstrapConf Configuration.
+   * @param name The configuration file name.
    * @return configuration
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   public abstract InputStream getConfigurationInputStream(
       Configuration bootstrapConf, String name) throws YarnException,
@@ -57,12 +57,15 @@ public abstract class ConfigurationProvider {
 
   /**
    * Derived classes initialize themselves using this method.
+   * @param bootstrapConf bootstrap configuration.
+   * @throws Exception exception occur.
    */
   public abstract void initInternal(Configuration bootstrapConf)
       throws Exception;
 
   /**
    * Derived classes close themselves using this method.
+   * @throws Exception exception occur.
    */
   public abstract void closeInternal() throws Exception;
 }

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/conf/ConfigurationProviderFactory.java

@@ -33,8 +33,8 @@ public class ConfigurationProviderFactory {
   /**
    * Creates an instance of {@link ConfigurationProvider} using given
    * configuration.
-   * @param bootstrapConf
-   * @return configurationProvider
+   * @param bootstrapConf bootstrap configuration.
+   * @return configurationProvider configuration provider.
    */
   @SuppressWarnings("unchecked")
   public static ConfigurationProvider

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/conf/HAUtil.java

@@ -102,7 +102,7 @@ public class HAUtil {
   /**
    * Verify configuration for Resource Manager HA.
    * @param conf Configuration
-   * @throws YarnRuntimeException
+   * @throws YarnRuntimeException thrown by a remote service.
    */
   public static void verifyAndSetConfiguration(Configuration conf)
     throws YarnRuntimeException {
@@ -320,7 +320,10 @@ public class HAUtil {
   }
 
   /**
-   * Add non empty and non null suffix to a key.
+   * Add non-empty and non-null suffix to a key.
+   *
+   * @param key key.
+   * @param suffix suffix.
    * @return the suffixed key
    */
   public static String addSuffix(String key, String suffix) {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/conf/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Public
+@Public
 package org.apache.hadoop.yarn.conf;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Public;
 

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/exceptions/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,6 +15,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Public
+@Public
 package org.apache.hadoop.yarn.exceptions;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Public;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/factories/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,6 +15,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Private
+@Private
 package org.apache.hadoop.yarn.factories;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Private;

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/factory/providers/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Private
+@Private
 package org.apache.hadoop.yarn.factory.providers;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Private;
 

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/server/api/ResourceManagerAdministrationProtocol.java

@@ -106,8 +106,8 @@ public interface ResourceManagerAdministrationProtocol extends GetUserMappingsPr
    * 
    * @param request request to update resource for a node in cluster.
    * @return (empty) response on accepting update.
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Private
   @Idempotent

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/server/api/SCMAdminProtocol.java

@@ -42,8 +42,8 @@ public interface SCMAdminProtocol {
    * @param request request <code>SharedCacheManager</code> to run a cleaner task
    * @return <code>SharedCacheManager</code> returns an empty response
    *         on success and throws an exception on rejecting the request
-   * @throws YarnException
-   * @throws IOException
+   * @throws YarnException exceptions from yarn servers.
+   * @throws IOException io error occur.
    */
   @Public
   @Unstable

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/server/api/protocolrecords/RefreshNodesRequest.java

@@ -54,16 +54,16 @@ public abstract class RefreshNodesRequest {
   }
 
   /**
-   * Set the DecommissionType
+   * Set the DecommissionType.
    * 
-   * @param decommissionType
+   * @param decommissionType decommission type.
    */
   public abstract void setDecommissionType(DecommissionType decommissionType);
 
   /**
-   * Get the DecommissionType
+   * Get the DecommissionType.
    * 
-   * @return decommissionType
+   * @return decommissionType decommission type.
    */
   public abstract DecommissionType getDecommissionType();
 

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/server/api/protocolrecords/package-info.java

@@ -1,4 +1,4 @@
-/*
+/**
  * Licensed to the Apache Software Foundation (ASF) under one
  * or more contributor license agreements.  See the NOTICE file
  * distributed with this work for additional information
@@ -15,7 +15,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-@InterfaceAudience.Private
+@Private
 package org.apache.hadoop.yarn.server.api.protocolrecords;
-import org.apache.hadoop.classification.InterfaceAudience;
+import org.apache.hadoop.classification.InterfaceAudience.Private;
 

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/util/constraint/PlacementConstraintParser.java

@@ -165,7 +165,8 @@ public final class PlacementConstraintParser {
 
     /**
      * Validate the schema before actual parsing the expression.
-     * @throws PlacementConstraintParseException
+     * @throws PlacementConstraintParseException when the placement constraint parser
+     * fails to parse an expression.
      */
     default void validate() throws PlacementConstraintParseException {
       // do nothing
@@ -633,9 +634,10 @@ public final class PlacementConstraintParser {
 
     /**
      * Parses source tags from expression "sourceTags(numOfAllocations)".
-     * @param expr
+     * @param expr expression string.
      * @return source tags, see {@link SourceTags}
-     * @throws PlacementConstraintParseException
+     * @throws PlacementConstraintParseException when the placement constraint parser
+     * fails to parse an expression.
      */
     public static SourceTags parseFrom(String expr)
         throws PlacementConstraintParseException {
@@ -718,7 +720,8 @@ public final class PlacementConstraintParser {
    * </ul>
    * @param expression expression string.
    * @return a map of source tags to placement constraint mapping.
-   * @throws PlacementConstraintParseException
+   * @throws PlacementConstraintParseException when the placement constraint parser
+   * fails to parse an expression.
    */
   public static Map<SourceTags, PlacementConstraint> parsePlacementSpec(
       String expression) throws PlacementConstraintParseException {

hadoop-yarn-project/hadoop-yarn/hadoop-yarn-api/src/main/java/org/apache/hadoop/yarn/util/csi/CsiConfigUtils.java

@@ -53,10 +53,10 @@ public final class CsiConfigUtils {
    * Resolve the CSI adaptor address for a CSI driver from configuration.
    * Expected configuration property name is
    * yarn.nodemanager.csi-driver-adaptor.${driverName}.address.
-   * @param driverName
-   * @param conf
+   * @param driverName driver name.
+   * @param conf configuration.
    * @return adaptor service address
-   * @throws YarnException
+   * @throws YarnException exceptions from yarn servers.
    */
   public static InetSocketAddress getCsiAdaptorAddressForDriver(
       String driverName, Configuration conf) throws YarnException {