HADOOP-15785. [JDK10] Javadoc build fails on JDK 10 in hadoop-common. Contributed by Dinesh Chitlangia.

Author: tasanuma

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

@@ -26,9 +26,15 @@
 @InterfaceStability.Stable
 public interface Configurable {
 
-  /** Set the configuration to be used by this object. */
+  /**
+   * Set the configuration to be used by this object.
+   * @param conf configuration to be used
+   */
   void setConf(Configuration conf);
 
-  /** Return the configuration used by this object. */
+  /**
+   * Return the configuration used by this object.
+   * @return Configuration
+   */
   Configuration getConf();
 }

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

@@ -115,7 +115,7 @@
 /**
  * Provides access to configuration parameters.
  *
- * <h4 id="Resources">Resources</h4>
+ * <h3 id="Resources">Resources</h3>
  *
  * <p>Configurations are specified by resources. A resource contains a set of
  * name/value pairs as XML data. Each resource is named by either a 
@@ -141,12 +141,12 @@
  * Once a resource declares a value final, no subsequently-loaded 
  * resource can alter that value.  
  * For example, one might define a final parameter with:
- * <tt><pre>
+ * <pre><code>
  *  &lt;property&gt;
  *    &lt;name&gt;dfs.hosts.include&lt;/name&gt;
  *    &lt;value&gt;/etc/hadoop/conf/hosts.include&lt;/value&gt;
  *    <b>&lt;final&gt;true&lt;/final&gt;</b>
- *  &lt;/property&gt;</pre></tt>
+ *  &lt;/property&gt;</code></pre>
  *
  * Administrators typically define parameters as final in 
  * <tt>core-site.xml</tt> for values that user applications may not alter.
@@ -164,7 +164,7 @@
  *
  * <p>For example, if a configuration resource contains the following property
  * definitions: 
- * <tt><pre>
+ * <pre><code>
  *  &lt;property&gt;
  *    &lt;name&gt;basedir&lt;/name&gt;
  *    &lt;value&gt;/user/${<i>user.name</i>}&lt;/value&gt;
@@ -179,7 +179,7 @@
  *    &lt;name&gt;otherdir&lt;/name&gt;
  *    &lt;value&gt;${<i>env.BASE_DIR</i>}/other&lt;/value&gt;
  *  &lt;/property&gt;
- *  </pre></tt>
+ *  </code></pre>
  *
  * <p>When <tt>conf.get("tempdir")</tt> is called, then <tt>${<i>basedir</i>}</tt>
  * will be resolved to another property in this Configuration, while
@@ -203,7 +203,7 @@
  * can define there own custom tags in  hadoop.tags.custom property.
  *
  * <p>For example, we can tag existing property as:
- * <tt><pre>
+ * <pre><code>
  *  &lt;property&gt;
  *    &lt;name&gt;dfs.replication&lt;/name&gt;
  *    &lt;value&gt;3&lt;/value&gt;
@@ -215,7 +215,7 @@
  *    &lt;value&gt;3&lt;/value&gt;
  *    &lt;tag&gt;HDFS,SECURITY&lt;/tag&gt;
  *  &lt;/property&gt;
- * </pre></tt>
+ * </code></pre>
  * <p> Properties marked with tags can be retrieved with <tt>conf
  * .getAllPropertiesByTag("HDFS")</tt> or <tt>conf.getAllPropertiesByTags
  * (Arrays.asList("YARN","SECURITY"))</tt>.</p>
@@ -581,9 +581,9 @@ public static void addDeprecations(DeprecationDelta[] deltas) {
    * If you have multiple deprecation entries to add, it is more efficient to
    * use #addDeprecations(DeprecationDelta[] deltas) instead.
    * 
-   * @param key
-   * @param newKeys
-   * @param customMessage
+   * @param key to be deprecated
+   * @param newKeys list of keys that take up the values of deprecated key
+   * @param customMessage depcrication message
    * @deprecated use {@link #addDeprecation(String key, String newKey,
       String customMessage)} instead
    */
@@ -605,9 +605,9 @@ public static void addDeprecation(String key, String[] newKeys,
    * If you have multiple deprecation entries to add, it is more efficient to
    * use #addDeprecations(DeprecationDelta[] deltas) instead.
    *
-   * @param key
-   * @param newKey
-   * @param customMessage
+   * @param key to be deprecated
+   * @param newKey key that take up the values of deprecated key
+   * @param customMessage deprecation message
    */
   public static void addDeprecation(String key, String newKey,
 	      String customMessage) {
@@ -1404,6 +1404,7 @@ void logDeprecationOnce(String name, String source) {
 
   /**
    * Unset a previously set property.
+   * @param name the property name
    */
   public synchronized void unset(String name) {
     String[] names = null;
@@ -1693,6 +1694,7 @@ public void setBooleanIfUnset(String name, boolean value) {
    * is equivalent to <code>set(&lt;name&gt;, value.toString())</code>.
    * @param name property name
    * @param value new value
+   * @param <T> enumeration type
    */
   public <T extends Enum<T>> void setEnum(String name, T value) {
     set(name, value.toString());
@@ -1703,8 +1705,10 @@ public <T extends Enum<T>> void setEnum(String name, T value) {
    * Note that the returned value is trimmed by this method.
    * @param name Property name
    * @param defaultValue Value returned if no mapping exists
+   * @param <T> enumeration type
    * @throws IllegalArgumentException If mapping is illegal for the type
    * provided
+   * @return enumeration type
    */
   public <T extends Enum<T>> T getEnum(String name, T defaultValue) {
     final String val = getTrimmed(name);
@@ -1784,6 +1788,7 @@ public void setTimeDuration(String name, long value, TimeUnit unit) {
    * @param unit Unit to convert the stored property, if it exists.
    * @throws NumberFormatException If the property stripped of its unit is not
    *         a number
+   * @return time duration in given time unit
    */
   public long getTimeDuration(String name, long defaultValue, TimeUnit unit) {
     return getTimeDuration(name, defaultValue, unit, unit);
@@ -2315,6 +2320,7 @@ public void setStrings(String name, String... values) {
    * the CredentialProvider API and conditionally fallsback to config.
    * @param name property name
    * @return password
+   * @throws IOException when error in fetching password
    */
   public char[] getPassword(String name) throws IOException {
     char[] pass = null;
@@ -2374,7 +2380,7 @@ private CredentialEntry getCredentialEntry(CredentialProvider provider,
    * alias.
    * @param name alias of the provisioned credential
    * @return password or null if not found
-   * @throws IOException
+   * @throws IOException when error in fetching password
    */
   public char[] getPasswordFromCredentialProviders(String name)
       throws IOException {
@@ -3483,25 +3489,23 @@ public void writeXml(@Nullable Writer out) throws IOException {
   /**
    * Write out the non-default properties in this configuration to the
    * given {@link Writer}.
-   *
+   * <ul>
    * <li>
    * When property name is not empty and the property exists in the
    * configuration, this method writes the property and its attributes
    * to the {@link Writer}.
    * </li>
-   * <p>
    *
    * <li>
    * When property name is null or empty, this method writes all the
    * configuration properties and their attributes to the {@link Writer}.
    * </li>
-   * <p>
    *
    * <li>
    * When property name is not empty but the property doesn't exist in
    * the configuration, this method throws an {@link IllegalArgumentException}.
    * </li>
-   * <p>
+   * </ul>
    * @param out the writer to write to.
    */
   public void writeXml(@Nullable String propertyName, Writer out)
@@ -3611,7 +3615,7 @@ private synchronized void appendXMLProperty(Document doc, Element conf,
   /**
    *  Writes properties and their attributes (final and resource)
    *  to the given {@link Writer}.
-   *
+   *  <ul>
    *  <li>
    *  When propertyName is not empty, and the property exists
    *  in the configuration, the format of the output would be,
@@ -3651,6 +3655,7 @@ private synchronized void appendXMLProperty(Document doc, Element conf,
    *  found in the configuration, this method will throw an
    *  {@link IllegalArgumentException}.
    *  </li>
+   *  </ul>
    *  <p>
    * @param config the configuration
    * @param propertyName property name
@@ -3849,7 +3854,7 @@ public void write(DataOutput out) throws IOException {
   /**
    * get keys matching the the regex 
    * @param regex
-   * @return Map<String,String> with matching keys
+   * @return {@literal Map<String,String>} with matching keys
    */
   public Map<String,String> getValByRegex(String regex) {
     Pattern p = Pattern.compile(regex);

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

@@ -41,7 +41,7 @@ public ConfigurationWithLogging(Configuration conf) {
   }
 
   /**
-   * @see Configuration#get(String).
+   * See {@link Configuration#get(String)}.
    */
   @Override
   public String get(String name) {
@@ -51,7 +51,7 @@ public String get(String name) {
   }
 
   /**
-   * @see Configuration#get(String, String).
+   * See {@link Configuration#get(String, String)}.
    */
   @Override
   public String get(String name, String defaultValue) {
@@ -62,7 +62,7 @@ public String get(String name, String defaultValue) {
   }
 
   /**
-   * @see Configuration#getBoolean(String, boolean).
+   * See {@link Configuration#getBoolean(String, boolean)}.
    */
   @Override
   public boolean getBoolean(String name, boolean defaultValue) {
@@ -72,7 +72,7 @@ public boolean getBoolean(String name, boolean defaultValue) {
   }
 
   /**
-   * @see Configuration#getFloat(String, float).
+   * See {@link Configuration#getFloat(String, float)}.
    */
   @Override
   public float getFloat(String name, float defaultValue) {
@@ -82,7 +82,7 @@ public float getFloat(String name, float defaultValue) {
   }
 
   /**
-   * @see Configuration#getInt(String, int).
+   * See {@link Configuration#getInt(String, int)}.
    */
   @Override
   public int getInt(String name, int defaultValue) {
@@ -92,7 +92,7 @@ public int getInt(String name, int defaultValue) {
   }
 
   /**
-   * @see Configuration#getLong(String, long).
+   * See {@link Configuration#getLong(String, long)}.
    */
   @Override
   public long getLong(String name, long defaultValue) {
@@ -102,7 +102,7 @@ public long getLong(String name, long defaultValue) {
   }
 
   /**
-   * @see Configuration#set(String, String, String).
+   * See {@link Configuration#set(String, String, String)}.
    */
   @Override
   public void set(String name, String value, String source) {

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

@@ -158,14 +158,15 @@ private static List<Class<? extends CryptoCodec>> getCodecClasses(
    * For example a {@link javax.crypto.Cipher} will maintain its encryption 
    * context internally when we do encryption/decryption using the 
    * Cipher#update interface. 
-   * <p/>
+   * <p>
    * Encryption/Decryption is not always on the entire file. For example,
    * in Hadoop, a node may only decrypt a portion of a file (i.e. a split).
    * In these situations, the counter is derived from the file position.
-   * <p/>
+   * <p>
    * The IV can be calculated by combining the initial IV and the counter with 
    * a lossless operation (concatenation, addition, or XOR).
-   * @see http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_.28CTR.29
+   * See http://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Counter_
+   * .28CTR.29
    * 
    * @param initIV initial IV
    * @param counter counter for input stream position 

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

@@ -54,10 +54,10 @@
  * required in order to ensure that the plain text and cipher text have a 1:1
  * mapping. The decryption is buffer based. The key points of the decryption
  * are (1) calculating the counter and (2) padding through stream position:
- * <p/>
+ * <p>
  * counter = base + pos/(algorithm blocksize); 
  * padding = pos%(algorithm blocksize); 
- * <p/>
+ * <p>
  * The underlying stream offset is maintained as state.
  */
 @InterfaceAudience.Private

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

@@ -36,10 +36,10 @@
  * required in order to ensure that the plain text and cipher text have a 1:1
  * mapping. The encryption is buffer based. The key points of the encryption are
  * (1) calculating counter and (2) padding through stream position.
- * <p/>
+ * <p>
  * counter = base + pos/(algorithm blocksize); 
  * padding = pos%(algorithm blocksize); 
- * <p/>
+ * <p>
  * The underlying stream offset is maintained as state.
  *
  * Note that while some of this class' methods are synchronized, this is just to

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

@@ -38,7 +38,7 @@ public interface Decryptor {
 
   /**
    * Indicate whether the decryption context is reset.
-   * <p/>
+   * <p>
    * Certain modes, like CTR, require a different IV depending on the 
    * position in the stream. Generally, the decryptor maintains any necessary
    * context for calculating the IV and counter so that no reinit is necessary 
@@ -49,22 +49,22 @@ public interface Decryptor {
 
   /**
    * This presents a direct interface decrypting with direct ByteBuffers.
-   * <p/>
+   * <p>
    * This function does not always decrypt the entire buffer and may potentially
    * need to be called multiple times to process an entire buffer. The object 
    * may hold the decryption context internally.
-   * <p/>
+   * <p>
    * Some implementations may require sufficient space in the destination 
    * buffer to decrypt the entire input buffer.
-   * <p/>
+   * <p>
    * Upon return, inBuffer.position() will be advanced by the number of bytes
    * read and outBuffer.position() by bytes written. Implementations should 
    * not modify inBuffer.limit() and outBuffer.limit().
-   * <p/>
+   * <p>
    * @param inBuffer a direct {@link ByteBuffer} to read from. inBuffer may 
-   * not be null and inBuffer.remaining() must be > 0
+   * not be null and inBuffer.remaining() must be {@literal >} 0
    * @param outBuffer a direct {@link ByteBuffer} to write to. outBuffer may 
-   * not be null and outBuffer.remaining() must be > 0
+   * not be null and outBuffer.remaining() must be {@literal >} 0
    * @throws IOException if decryption fails
    */
   public void decrypt(ByteBuffer inBuffer, ByteBuffer outBuffer) 

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

@@ -37,7 +37,7 @@ public interface Encryptor {
 
   /**
    * Indicate whether the encryption context is reset.
-   * <p/>
+   * <p>
    * Certain modes, like CTR, require a different IV depending on the
    * position in the stream. Generally, the encryptor maintains any necessary
    * context for calculating the IV and counter so that no reinit is necessary
@@ -48,22 +48,22 @@ public interface Encryptor {
 
   /**
    * This presents a direct interface encrypting with direct ByteBuffers.
-   * <p/>
+   * <p>
    * This function does not always encrypt the entire buffer and may potentially
    * need to be called multiple times to process an entire buffer. The object 
    * may hold the encryption context internally.
-   * <p/>
+   * <p>
    * Some implementations may require sufficient space in the destination 
    * buffer to encrypt the entire input buffer.
-   * <p/>
+   * <p>
    * Upon return, inBuffer.position() will be advanced by the number of bytes
    * read and outBuffer.position() by bytes written. Implementations should
    * not modify inBuffer.limit() and outBuffer.limit().
-   * <p/>
+   * <p>
    * @param inBuffer a direct {@link ByteBuffer} to read from. inBuffer may 
-   * not be null and inBuffer.remaining() must be > 0
+   * not be null and inBuffer.remaining() must be &gt; 0
    * @param outBuffer a direct {@link ByteBuffer} to write to. outBuffer may 
-   * not be null and outBuffer.remaining() must be > 0
+   * not be null and outBuffer.remaining() must be &gt; 0
    * @throws IOException if encryption fails
    */
   public void encrypt(ByteBuffer inBuffer, ByteBuffer outBuffer)