HADOOP-18229. Fix Hadoop-Common JavaDoc Error

hadoop-common-project/hadoop-common/pom.xml

@@ -1171,6 +1171,16 @@
               </execution>
              </executions>
           </plugin>
+          <plugin>
+            <groupId>org.apache.maven.plugins</groupId>
+            <artifactId>maven-javadoc-plugin</artifactId>
+            <configuration>
+              <sourceFileExcludes>
+                <sourceFileExclude>**/FSProtos.java</sourceFileExclude>
+              </sourceFileExcludes>
+              <excludePackageNames>*.proto:*.tracing:*.protobuf</excludePackageNames>
+            </configuration>
+          </plugin>
         </plugins>
       </build>
     </profile>

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/ConfigRedactor.java

@@ -57,8 +57,8 @@ public ConfigRedactor(Configuration conf) {
    * Given a key / value pair, decides whether or not to redact and returns
    * either the original value or text indicating it has been redacted.
    *
-   * @param key
-   * @param value
+   * @param key param key.
+   * @param value param value, will return if conditions permit.
    * @return Original value, or text indicating it has been redacted
    */
   public String redact(String key, String value) {

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/Configuration.java

@@ -317,7 +317,7 @@ private static boolean getRestrictParserDefault(Object resource) {
   private boolean loadDefaults = true;
 
   /**
-   * Configuration objects
+   * Configuration objects.
    */
   private static final WeakHashMap<Configuration,Object> REGISTRY = 
     new WeakHashMap<Configuration,Object>();
@@ -1908,6 +1908,7 @@ public long getTimeDuration(String name, String defaultValue,
    * @param name Property name
    * @param vStr The string value with time unit suffix to be converted.
    * @param unit Unit to convert the stored property, if it exists.
+   * @return time duration in given time unit.
    */
   public long getTimeDurationHelper(String name, String vStr, TimeUnit unit) {
     return getTimeDurationHelper(name, vStr, unit, unit);
@@ -1922,6 +1923,7 @@ public long getTimeDurationHelper(String name, String vStr, TimeUnit unit) {
    * @param vStr The string value with time unit suffix to be converted.
    * @param defaultUnit Unit to convert the stored property, if it exists.
    * @param returnUnit Unit for the returned value.
+   * @return time duration in given time unit.
    */
   private long getTimeDurationHelper(String name, String vStr,
       TimeUnit defaultUnit, TimeUnit returnUnit) {
@@ -2206,7 +2208,7 @@ private static int convertToInt(String value, int defaultValue) {
     }
 
     /**
-     * Is the given value in the set of ranges
+     * Is the given value in the set of ranges.
      * @param value the value to check
      * @return is the value in the ranges?
      */
@@ -2263,7 +2265,7 @@ public Iterator<Integer> iterator() {
   }
 
   /**
-   * Parse the given attribute as a set of integer ranges
+   * Parse the given attribute as a set of integer ranges.
    * @param name the attribute name
    * @param defaultValue the default value if it is not set
    * @return a new set of ranges from the configured value
@@ -2482,7 +2484,7 @@ public char[] getPasswordFromCredentialProviders(String name)
 
   /**
    * Fallback to clear text passwords in configuration.
-   * @param name
+   * @param name the property name.
    * @return clear text password or null
    */
   protected char[] getPasswordFromConfig(String name) {
@@ -2547,6 +2549,8 @@ public InetSocketAddress getSocketAddr(
   /**
    * Set the socket address for the <code>name</code> property as
    * a <code>host:port</code>.
+   * @param name property name.
+   * @param addr inetSocketAddress addr.
    */
   public void setSocketAddr(String name, InetSocketAddress addr) {
     set(name, NetUtils.getHostPortString(addr));
@@ -2724,6 +2728,7 @@ public Class<?> getClass(String name, Class<?> defaultValue) {
    * @param name the conf key name.
    * @param defaultValue default value.
    * @param xface the interface implemented by the named class.
+   * @param <U> Interface class type.
    * @return property value as a <code>Class</code>, 
    *         or <code>defaultValue</code>.
    */
@@ -2753,6 +2758,7 @@ else if (theClass != null)
    * @param name the property name.
    * @param xface the interface implemented by the classes named by
    *        <code>name</code>.
+   * @param <U> Interface class type.
    * @return a <code>List</code> of objects implementing <code>xface</code>.
    */
   @SuppressWarnings("unchecked")
@@ -2785,15 +2791,16 @@ public void setClass(String name, Class<?> theClass, Class<?> xface) {
     set(name, theClass.getName());
   }
 
-  /** 
+  /**
    * Get a local file under a directory named by <i>dirsProp</i> with
    * the given <i>path</i>.  If <i>dirsProp</i> contains multiple directories,
    * then one is chosen based on <i>path</i>'s hash code.  If the selected
    * directory does not exist, an attempt is made to create it.
-   * 
+   *
    * @param dirsProp directory in which to locate the file.
    * @param path file-path.
    * @return local file under the directory with the given path.
+   * @throws IOException raised on errors performing I/O.
    */
   public Path getLocalPath(String dirsProp, String path)
     throws IOException {
@@ -2817,15 +2824,16 @@ public Path getLocalPath(String dirsProp, String path)
     throw new IOException("No valid local directories in property: "+dirsProp);
   }
 
-  /** 
+  /**
    * Get a local file name under a directory named in <i>dirsProp</i> with
    * the given <i>path</i>.  If <i>dirsProp</i> contains multiple directories,
    * then one is chosen based on <i>path</i>'s hash code.  If the selected
    * directory does not exist, an attempt is made to create it.
-   * 
+   *
    * @param dirsProp directory in which to locate the file.
    * @param path file-path.
    * @return local file under the directory with the given path.
+   * @throws IOException raised on errors performing I/O.
    */
   public File getFile(String dirsProp, String path)
     throws IOException {
@@ -3437,7 +3445,7 @@ void parseNext() throws IOException, XMLStreamException {
 
   /**
    * Add tags defined in HADOOP_TAGS_SYSTEM, HADOOP_TAGS_CUSTOM.
-   * @param prop
+   * @param prop properties.
    */
   public void addTags(Properties prop) {
     // Get all system tags
@@ -3538,7 +3546,7 @@ private void loadProperty(Properties properties, String name, String attr,
 
   /**
    * Print a warning if a property with a given name already exists with a
-   * different value
+   * different value.
    */
   private void checkForOverride(Properties properties, String name, String attr, String value) {
     String propertyValue = properties.getProperty(attr);
@@ -3548,11 +3556,12 @@ private void checkForOverride(Properties properties, String name, String attr, S
     }
   }
 
-  /** 
+  /**
    * Write out the non-default properties in this configuration to the given
    * {@link OutputStream} using UTF-8 encoding.
-   * 
+   *
    * @param out the output stream to write to.
+   * @throws IOException raised on errors performing I/O.
    */
   public void writeXml(OutputStream out) throws IOException {
     writeXml(new OutputStreamWriter(out, "UTF-8"));
@@ -3582,7 +3591,9 @@ public void writeXml(Writer out) throws IOException {
    * the configuration, this method throws an {@link IllegalArgumentException}.
    * </li>
    * </ul>
+   * @param propertyName xml property name.
    * @param out the writer to write to.
+   * @throws IOException raised on errors performing I/O.
    */
   public void writeXml(@Nullable String propertyName, Writer out)
       throws IOException, IllegalArgumentException {
@@ -3736,7 +3747,7 @@ private synchronized void appendXMLProperty(Document doc, Element conf,
    * @param config the configuration
    * @param propertyName property name
    * @param out the Writer to write to
-   * @throws IOException
+   * @throws IOException raised on errors performing I/O.
    * @throws IllegalArgumentException when property name is not
    *   empty and the property is not found in configuration
    **/
@@ -3783,7 +3794,7 @@ public static void dumpConfiguration(Configuration config,
    *
    * @param config the configuration
    * @param out the Writer to write to
-   * @throws IOException
+   * @throws IOException raised on errors performing I/O.
    */
   public static void dumpConfiguration(Configuration config,
       Writer out) throws IOException {
@@ -3812,7 +3823,7 @@ public static void dumpConfiguration(Configuration config,
    * @param jsonGen json writer
    * @param config configuration
    * @param name property name
-   * @throws IOException
+   * @throws IOException raised on errors performing I/O.
    */
   private static void appendJSONProperty(JsonGenerator jsonGen,
       Configuration config, String name, ConfigRedactor redactor)
@@ -3894,7 +3905,10 @@ synchronized boolean getQuietMode() {
     return this.quietmode;
   }
 
-  /** For debugging.  List non-default properties to the terminal and exit. */
+  /** For debugging.  List non-default properties to the terminal and exit.
+   * @param args the argument to be parsed.
+   * @throws Exception exception.
+   */
   public static void main(String[] args) throws Exception {
     new Configuration().writeXml(System.out);
   }
@@ -3928,8 +3942,8 @@ public void write(DataOutput out) throws IOException {
   }
 
   /**
-   * get keys matching the the regex 
-   * @param regex
+   * get keys matching the the regex.
+   * @param regex the regex to match against.
    * @return {@literal Map<String,String>} with matching keys
    */
   public Map<String,String> getValByRegex(String regex) {
@@ -3974,6 +3988,8 @@ public static void dumpDeprecatedKeys() {
   /**
    * Returns whether or not a deprecated name has been warned. If the name is not
    * deprecated then always return false
+   * @param name proprties.
+   * @return true if name is a warned deprecation.
    */
   public static boolean hasWarnedDeprecation(String name) {
     DeprecationContext deprecations = deprecationContext.get();

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/Configured.java

@@ -33,7 +33,9 @@ public Configured() {
     this(null);
   }
 
-  /** Construct a Configured. */
+  /** Construct a Configured.
+   * @param conf the Configuration object.
+   */
   public Configured(Configuration conf) {
     setConf(conf);
   }

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/Reconfigurable.java

@@ -33,6 +33,9 @@ public interface Reconfigurable extends Configurable {
    * (or null if it was not previously set). If newVal is null, set the property
    * to its default value;
    *
+   * @param property property name.
+   * @param newVal new value.
+   * @throws ReconfigurationException if there was an error applying newVal.
    * If the property cannot be changed, throw a 
    * {@link ReconfigurationException}.
    */
@@ -45,11 +48,14 @@ void reconfigureProperty(String property, String newVal)
    * If isPropertyReconfigurable returns true for a property,
    * then changeConf should not throw an exception when changing
    * this property.
+   * @param property property name.
+   * @return true if property reconfigurable; false if not.
    */
   boolean isPropertyReconfigurable(String property);
 
   /**
    * Return all the properties that can be changed at run time.
+   * @return reconfigurable propertys.
    */
   Collection<String> getReconfigurableProperties();
 }

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/ReconfigurableBase.java

@@ -79,6 +79,7 @@ public ReconfigurableBase() {
   /**
    * Construct a ReconfigurableBase with the {@link Configuration}
    * conf.
+   * @param conf configuration.
    */
   public ReconfigurableBase(Configuration conf) {
     super((conf == null) ? new Configuration() : conf);
@@ -91,6 +92,7 @@ public void setReconfigurationUtil(ReconfigurationUtil ru) {
 
   /**
    * Create a new configuration.
+   * @return configuration.
    */
   protected abstract Configuration getNewConf();
 
@@ -162,6 +164,7 @@ public void run() {
 
   /**
    * Start a reconfiguration task to reload configuration in background.
+   * @throws IOException raised on errors performing I/O.
    */
   public void startReconfigurationTask() throws IOException {
     synchronized (reconfigLock) {

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/ReconfigurationException.java

@@ -59,6 +59,10 @@ public ReconfigurationException() {
 
   /**
    * Create a new instance of {@link ReconfigurationException}.
+   * @param property property name.
+   * @param newVal new value.
+   * @param oldVal old value.
+   * @param cause original exception.
    */
   public ReconfigurationException(String property, 
                                   String newVal, String oldVal,
@@ -71,6 +75,9 @@ public ReconfigurationException(String property,
 
   /**
    * Create a new instance of {@link ReconfigurationException}.
+   * @param property property name.
+   * @param newVal new value.
+   * @param oldVal old value.
    */
   public ReconfigurationException(String property, 
                                   String newVal, String oldVal) {
@@ -82,20 +89,23 @@ public ReconfigurationException(String property,
 
   /**
    * Get property that cannot be changed.
+   * @return property info.
    */
   public String getProperty() {
     return property;
   }
 
   /**
    * Get value to which property was supposed to be changed.
+   * @return new value.
    */
   public String getNewValue() {
     return newVal;
   }
 
   /**
    * Get old value of property that cannot be changed.
+   * @return old value.
    */
   public String getOldValue() {
     return oldVal;

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/conf/ReconfigurationTaskStatus.java

@@ -42,7 +42,8 @@ public ReconfigurationTaskStatus(long startTime, long endTime,
   /**
    * Return true if
    *   - A reconfiguration task has finished or
-   *   - an active reconfiguration task is running
+   *   - an active reconfiguration task is running.
+   * @return true if startTime > 0; false if not.
    */
   public boolean hasTask() {
     return startTime > 0;
@@ -51,6 +52,7 @@ public boolean hasTask() {
   /**
    * Return true if the latest reconfiguration task has finished and there is
    * no another active task running.
+   * @return true if endTime > 0; false if not.
    */
   public boolean stopped() {
     return endTime > 0;

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/CryptoCodec.java

@@ -145,14 +145,18 @@ private static List<Class<? extends CryptoCodec>> getCodecClasses(
   public abstract CipherSuite getCipherSuite();
 
   /**
-   * Create a {@link org.apache.hadoop.crypto.Encryptor}. 
-   * @return Encryptor the encryptor
+   * Create a {@link org.apache.hadoop.crypto.Encryptor}.
+   *
+   * @return Encryptor the encryptor.
+   * @throws GeneralSecurityException thrown if create encryptor error.
    */
   public abstract Encryptor createEncryptor() throws GeneralSecurityException;
-  
+
   /**
    * Create a {@link org.apache.hadoop.crypto.Decryptor}.
+   *
    * @return Decryptor the decryptor
+   * @throws GeneralSecurityException thrown if create decryptor error.
    */
   public abstract Decryptor createDecryptor() throws GeneralSecurityException;
 

hadoop-common-project/hadoop-common/src/main/java/org/apache/hadoop/crypto/CryptoInputStream.java

@@ -157,7 +157,7 @@ public InputStream getWrappedStream() {
    * @param off the buffer offset.
    * @param len the maximum number of decrypted data bytes to read.
    * @return int the total number of decrypted data bytes read into the buffer.
-   * @throws IOException
+   * @throws IOException raised on errors performing I/O.
    */
   @Override
   public int read(byte[] b, int off, int len) throws IOException {