YARN-5429. Fix return related javadoc warnings in yarn-api (Vrushali C via Varun Saxena)

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

@@ -263,6 +263,7 @@ public String toString() {
      * Note: Use $$() method for cross-platform practice i.e. submit an
      * application from a Windows client to a Linux/Unix server or vice versa.
      * </p>
+     * @return expanded environment variable.
      */
     public String $() {
       if (Shell.WINDOWS) {
@@ -278,6 +279,7 @@ public String toString() {
      * expansion marker ('%' for Windows and '$' for Linux) by NodeManager on
      * container launch. For example: {{VAR}} will be replaced as $VAR on Linux,
      * and %VAR% on Windows.
+     * @return expanded environment variable.
      */
     @Public
     @Unstable

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

@@ -199,6 +199,9 @@ public abstract void setResourceBlacklistRequest(
   /**
    * Get the list of container resource increase requests being sent by the
    * <code>ApplicationMaster</code>.
+   * @return the list of {@link ContainerResourceChangeRequest}
+   *         being sent by the
+   *         <code>ApplicationMaster</code>.
    */
   @Public
   @Unstable
@@ -208,6 +211,8 @@ public abstract void setResourceBlacklistRequest(
    * Set the list of container resource increase requests to inform the
    * <code>ResourceManager</code> about the containers whose resources need
    *         to be increased.
+   * @param increaseRequests list of
+   *        {@link ContainerResourceChangeRequest}
    */
   @Public
   @Unstable
@@ -217,6 +222,9 @@ public abstract void setIncreaseRequests(
   /**
    * Get the list of container resource decrease requests being sent by the
    * <code>ApplicationMaster</code>.
+   * @return list of {@link ContainerResourceChangeRequest}
+   *         being sent by the
+   *         <code>ApplicationMaster</code>.
    */
   @Public
   @Unstable
@@ -226,6 +234,8 @@ public abstract void setIncreaseRequests(
    * Set the list of container resource decrease requests to inform the
    * <code>ResourceManager</code> about the containers whose resources need
    * to be decreased.
+   * @param decreaseRequests list of
+   *        {@link ContainerResourceChangeRequest}
    */
   @Public
   @Unstable

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

@@ -279,6 +279,7 @@ public static AllocateResponse newInstance(int responseId,
    * AM will receive one NMToken per NM irrespective of the number of containers
    * issued on same NM. AM is expected to store these tokens until issued a
    * new token for the same NM.
+   * @return list of NMTokens required for communicating with NM
    */
   @Public
   @Stable
@@ -291,6 +292,7 @@ public static AllocateResponse newInstance(int responseId,
   /**
    * Get the list of newly increased containers by
    * <code>ResourceManager</code>.
+   * @return list of newly increased containers
    */
   @Public
   @Unstable
@@ -308,6 +310,7 @@ public abstract void setIncreasedContainers(
   /**
    * Get the list of newly decreased containers by
    * <code>ResourceManager</code>.
+   * @return the list of newly decreased containers
    */
   @Public
   @Unstable

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

@@ -59,6 +59,8 @@ public static FinishApplicationMasterResponse newInstance(
   /**
    * Get the flag which indicates that the application has successfully
    * unregistered with the RM and the application can safely stop.
+   * @return true if the application has unregistered with the RM,
+   *         false otherwise
    */
   @Public
   @Stable
@@ -67,6 +69,8 @@ public static FinishApplicationMasterResponse newInstance(
   /**
    * Set the flag which indicates that the application has successfully
    * unregistered with the RM and the application can safely stop.
+   * @param isUnregistered boolean flag to indicate that the application has
+   *        successfully unregistered with the RM
    */
   @Private
   @Unstable

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

@@ -116,6 +116,7 @@ public static GetApplicationsRequest newInstance(
    *
    * @param scope {@link ApplicationsRequestScope} to filter by
    * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
+   * @return a report of Applications in {@link GetApplicationsRequest}
    */
   @Public
   @Stable
@@ -136,6 +137,7 @@ public static GetApplicationsRequest newInstance(
    *
    *
    * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
+   * @return a report of Applications in {@link GetApplicationsRequest}
    */
   @Public
   @Stable
@@ -156,6 +158,7 @@ public static GetApplicationsRequest newInstance(
    *
    *
    * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
+   * @return  a report of Applications in {@link GetApplicationsRequest}
    */
   @Public
   @Stable
@@ -176,6 +179,7 @@ public static GetApplicationsRequest newInstance(
    *
    *
    * @see ApplicationClientProtocol#getApplications(GetApplicationsRequest)
+   * @return  a report of Applications in <code>GetApplicationsRequest</code>
    */
   @Public
   @Stable

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

@@ -56,11 +56,13 @@ public static GetClusterNodesRequest newInstance() {
   
   /**
    * The state to filter the cluster nodes with.
+   * @return the set of {@link NodeState}
    */
   public abstract EnumSet<NodeState> getNodeStates();
   
   /**
    * The state to filter the cluster nodes with.
+   * @param states the set of {@link NodeState}
    */
   public abstract void setNodeStates(EnumSet<NodeState> states);
 }

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

@@ -73,6 +73,7 @@ public static GetContainerStatusesResponse newInstance(
   /**
    * Get the containerId-to-exception map in which the exception indicates error
    * from per container for failed requests
+   * @return map of containerId-to-exception
    */
   @Public
   @Stable

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

@@ -49,7 +49,7 @@ public static GetDelegationTokenResponse newInstance(Token rmDTToken) {
   /**
    * The Delegation tokens have a identifier which maps to
    * {@link AbstractDelegationTokenIdentifier}.
-   *
+   * @return the delegation tokens
    */
   @Public
   @Stable

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

@@ -77,6 +77,7 @@ public abstract void setSuccessfullyIncreasedContainers(
   /**
    * Get the containerId-to-exception map in which the exception indicates
    * error from each container for failed requests.
+   * @return map of containerId-to-exception
    */
   @Public
   @Unstable

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

@@ -57,6 +57,8 @@ public static KillApplicationResponse newInstance(boolean isKillCompleted) {
 
   /**
    * Get the flag which indicates that the process of killing application is completed or not.
+   * @return true if the process of killing application has completed,
+   *         false otherwise
    */
   @Public
   @Stable

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

@@ -104,6 +104,7 @@ public static RegisterApplicationMasterResponse newInstance(
    * <p>The ClientToAMToken master key is sent to <code>ApplicationMaster</code>
    * by <code>ResourceManager</code> via {@link RegisterApplicationMasterResponse}
    * , used to verify corresponding ClientToAMToken.</p>
+   * @return ClientToAMToken master key
    */
   @Public
   @Stable
@@ -118,6 +119,7 @@ public static RegisterApplicationMasterResponse newInstance(
 
   /**
    * <p>Get the queue that the application was placed in.<p>
+   * @return the queue that the application was placed in.
    */
   @Public
   @Stable

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

@@ -52,6 +52,7 @@ public abstract class ReservationListRequest {
    *                to be returned. Reservation allocations are subject to
    *                change in the event of re-planning as described by
    *                {@code ReservationDefinition}.
+   * @return the list of reservations via  {@link ReservationListRequest}
    */
   @Public
   @Unstable
@@ -84,6 +85,7 @@ public static ReservationListRequest newInstance(
    *                to be returned. Reservation allocations are subject to
    *                change in the event of re-planning as described by
    *                {@code ReservationDefinition}.
+   * @return the list of reservations via {@link ReservationListRequest}
    */
   @Public
   @Unstable
@@ -105,6 +107,7 @@ public static ReservationListRequest newInstance(
    * @param reservationId Optional. String representation of
    *                     {@code ReservationId} If provided, other fields will
    *                     be ignored.
+   * @return the list of reservations via {@link ReservationListRequest}
    */
   @Public
   @Unstable

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

@@ -78,6 +78,7 @@ public abstract void setSuccessfullyStartedContainers(
   /**
    * Get the containerId-to-exception map in which the exception indicates error
    * from per container for failed requests
+   * @return map of containerId-to-exception
    */
   @Public
   @Stable

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

@@ -74,6 +74,7 @@ public abstract void setSuccessfullyStoppedContainers(
   /**
    * Get the containerId-to-exception map in which the exception indicates error
    * from per container for failed requests
+   * @return map of containerId-to-exception
    */
   @Public
   @Stable

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

@@ -193,6 +193,9 @@ public static LocalResource newInstance(URL url, LocalResourceType type,
   /**
    * NM uses it to decide whether if it is necessary to upload the resource to
    * the shared cache
+   * @return true if it is necessary to upload the resource
+   *                 to the shared cache,
+   *         false otherwise
    */
   @Public
   @Unstable

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

@@ -263,7 +263,10 @@ public static String getConfValueForRMInstance(
     return (value == null) ? defaultValue : value;
   }
 
-  /** Add non empty and non null suffix to a key */
+  /**
+   * Add non empty and non null suffix to a key.
+   * @return the suffixed key
+   */
   public static String addSuffix(String key, String suffix) {
     if (suffix == null || suffix.isEmpty()) {
       return key;