HBASE-6926 Cleanup some of the javadoc warnings

git-svn-id: https://svn.apache.org/repos/asf/hbase/trunk@1393168 13f79535-47bb-0310-9956-ffa450edef68

hbase-common/src/main/java/org/apache/hadoop/hbase/HConstants.java

@@ -543,11 +543,11 @@ public final class HConstants {
   /**
    * Parameter name for unique identifier for this {@link org.apache.hadoop.conf.Configuration}
    * instance. If there are two or more {@link org.apache.hadoop.conf.Configuration} instances that,
-   * for all intents and purposes, are the same except for their instance ids,
+   * for all intents and purposes, are the same except for their instance ids, then they will not be
-   * then they will not be able to share the same {@link org.apache.hadoop.hbase.client.HConnection} instance.
+   * able to share the same org.apache.hadoop.hbase.client.HConnection instance. On the other hand,
-   * On the other hand, even if the instance ids are the same, it could result
+   * even if the instance ids are the same, it could result in non-shared
-   * in non-shared {@link org.apache.hadoop.hbase.client.HConnection}
+   * org.apache.hadoop.hbase.client.HConnection instances if some of the other connection parameters
-   * instances if some of the other connection parameters differ.
+   * differ.
    */
   public static String HBASE_CLIENT_INSTANCE_ID = "hbase.client.instance.id";
 

hbase-common/src/main/java/org/apache/hadoop/hbase/KeyValue.java

@@ -41,30 +41,25 @@ import org.apache.hadoop.io.Writable;
 import com.google.common.primitives.Longs;
 
 /**
- * An HBase Key/Value.  This is the fundamental HBase Type.
+ * An HBase Key/Value. This is the fundamental HBase Type.
- *
+ * <p>
- * <p>If being used client-side, the primary methods to access individual fields
+ * If being used client-side, the primary methods to access individual fields are {@link #getRow()},
- * are {@link #getRow()}, {@link #getFamily()}, {@link #getQualifier()},
+ * {@link #getFamily()}, {@link #getQualifier()}, {@link #getTimestamp()}, and {@link #getValue()}.
- * {@link #getTimestamp()}, and {@link #getValue()}.  These methods allocate new
+ * These methods allocate new byte arrays and return copies. Avoid their use server-side.
- * byte arrays and return copies. Avoid their use server-side.
+ * <p>
- *
+ * Instances of this class are immutable. They do not implement Comparable but Comparators are
- * <p>Instances of this class are immutable.  They do not implement Comparable
+ * provided. Comparators change with context, whether user table or a catalog table comparison. Its
- * but Comparators are provided.  Comparators change with context,
+ * critical you use the appropriate comparator. There are Comparators for KeyValue instances and
- * whether user table or a catalog table comparison.  Its critical you use the
+ * then for just the Key portion of a KeyValue used mostly by HFile.
- * appropriate comparator.  There are Comparators for KeyValue instances and
+ * <p>
- * then for just the Key portion of a KeyValue used mostly by {@link HFile}.
+ * KeyValue wraps a byte array and takes offsets and lengths into passed array at where to start
- *
+ * interpreting the content as KeyValue. The KeyValue format inside a byte array is:
- * <p>KeyValue wraps a byte array and takes offsets and lengths into passed
+ * <code>&lt;keylength> &lt;valuelength> &lt;key> &lt;value></code> Key is further decomposed as:
- * array at where to start interpreting the content as KeyValue.  The KeyValue
- * format inside a byte array is:
- * <code>&lt;keylength> &lt;valuelength> &lt;key> &lt;value></code>
- * Key is further decomposed as:
  * <code>&lt;rowlength> &lt;row> &lt;columnfamilylength> &lt;columnfamily> &lt;columnqualifier> &lt;timestamp> &lt;keytype></code>
- * The <code>rowlength</code> maximum is <code>Short.MAX_SIZE</code>,
+ * The <code>rowlength</code> maximum is <code>Short.MAX_SIZE</code>, column family length maximum
- * column family length maximum is
+ * is <code>Byte.MAX_SIZE</code>, and column qualifier + key length must be <
- * <code>Byte.MAX_SIZE</code>, and column qualifier + key length must
+ * <code>Integer.MAX_SIZE</code>. The column does not contain the family/qualifier delimiter,
- * be < <code>Integer.MAX_SIZE</code>.
+ * {@link #COLUMN_FAMILY_DELIMITER}
- * The column does not contain the family/qualifier delimiter, {@link #COLUMN_FAMILY_DELIMITER}
  */
 @InterfaceAudience.Public
 @InterfaceStability.Evolving

hbase-common/src/main/java/org/apache/hadoop/hbase/io/hfile/BlockType.java

@@ -29,9 +29,8 @@ import org.apache.hadoop.classification.InterfaceAudience;
 import org.apache.hadoop.hbase.util.Bytes;
 
 /**
- * Various types of {@link HFile} blocks. Ordinal values of these enum constants
+ * Various types of HFile blocks. Ordinal values of these enum constants must not be relied upon.
- * must not be relied upon. The values in the enum appear in the order they
+ * The values in the enum appear in the order they appear in a version 2 HFile.
- * appear in a version 2 {@link HFile}.
  */
 @InterfaceAudience.Private
 public enum BlockType {

hbase-hadoop1-compat/src/main/java/org/apache/hadoop/hbase/metrics/BaseMetricsSourceImpl.java

@@ -167,7 +167,7 @@ public class BaseMetricsSourceImpl implements BaseMetricsSource, MetricsSource {
 
   /**
    * Used to get at the DynamicMetricsRegistry.
-   * @return
+   * @return DynamicMetricsRegistry
    */
   protected DynamicMetricsRegistry getMetricsRegistry() {
     return metricsRegistry;

hbase-hadoop2-compat/src/main/java/org/apache/hadoop/metrics2/lib/DynamicMetricsRegistry.java

@@ -414,7 +414,6 @@ public class DynamicMetricsRegistry {
    *
    * @param gaugeName              name of the gauge to create or get.
    * @param potentialStartingValue value of the new gauge if we have to create it.
-   * @return
    */
   public MutableGaugeLong getLongGauge(String gaugeName, long potentialStartingValue) {
     //Try and get the guage.
@@ -450,7 +449,6 @@ public class DynamicMetricsRegistry {
    *
    * @param counterName            Name of the counter to get
    * @param potentialStartingValue starting value if we have to create a new counter
-   * @return
    */
   public MutableCounterLong getLongCounter(String counterName, long potentialStartingValue) {
     //See getLongGauge for description on how this works.

hbase-server/src/main/java/org/apache/hadoop/hbase/ClusterId.java

@@ -58,7 +58,7 @@ public class ClusterId {
    * @param bytes A pb serialized {@link ClusterId} instance with pb magic prefix
    * @return An instance of {@link ClusterId} made from <code>bytes</code>
    * @throws DeserializationException
-   * @see {@link #toByteArray()}
+   * @see #toByteArray()
    */
   public static ClusterId parseFrom(final byte [] bytes) throws DeserializationException {
     if (ProtobufUtil.isPBMagicPrefix(bytes)) {

hbase-server/src/main/java/org/apache/hadoop/hbase/HBaseException.java

@@ -21,7 +21,7 @@ import org.apache.hadoop.classification.InterfaceAudience;
 
 /**
  * Base checked exception in HBase.
- * @see https://issues.apache.org/jira/browse/HBASE-5796
+ * @see <a href="https://issues.apache.org/jira/browse/HBASE-5796">HBASE-5796</a>
  */
 @SuppressWarnings("serial")
 @InterfaceAudience.Private

hbase-server/src/main/java/org/apache/hadoop/hbase/HBaseIOException.java

@@ -35,23 +35,14 @@ public class HBaseIOException extends IOException {
     super();
   }
 
-  /**
-   * {@inheritDoc}
-   */
   public HBaseIOException(String message) {
     super(message);
   }
 
-  /**
-   * {@inheritDoc}
-   **/
   public HBaseIOException(String message, Throwable cause) {
       super(message, cause);
   }
 
-  /**
-   * {@inheritDoc}
-   */
   public HBaseIOException(Throwable cause) {
       super(cause);
   }}

hbase-server/src/main/java/org/apache/hadoop/hbase/HColumnDescriptor.java

@@ -1086,7 +1086,7 @@ public class HColumnDescriptor implements WritableComparable<HColumnDescriptor>
 
   /**
    * @return This instance serialized with pb with pb magic prefix
-   * @see {@link #parseFrom(byte[])}
+   * @see #parseFrom(byte[])
    */
   public byte [] toByteArray() {
     return ProtobufUtil.prependPBMagic(convert().toByteArray());
@@ -1096,7 +1096,7 @@ public class HColumnDescriptor implements WritableComparable<HColumnDescriptor>
    * @param bytes A pb serialized {@link HColumnDescriptor} instance with pb magic prefix
    * @return An instance of {@link HColumnDescriptor} made from <code>bytes</code>
    * @throws DeserializationException
-   * @see {@link #toByteArray()}
+   * @see #toByteArray()
    */
   public static HColumnDescriptor parseFrom(final byte [] bytes) throws DeserializationException {
     if (!ProtobufUtil.isPBMagicPrefix(bytes)) throw new DeserializationException("No magic");

hbase-server/src/main/java/org/apache/hadoop/hbase/HRegionInfo.java

@@ -731,8 +731,8 @@ public class HRegionInfo implements Comparable<HRegionInfo> {
   }
 
   /**
-   * @deprecated Use protobuf deserialization instead. See {@link #parseFrom(byte[])} and
+   * @deprecated Use protobuf deserialization instead. 
-   * {@link #parseFrom(FSDataInputStream)}
+   * @see #parseFrom(byte[])
    */
   @Deprecated
   public void readFields(DataInput in) throws IOException {
@@ -914,7 +914,7 @@ public class HRegionInfo implements Comparable<HRegionInfo> {
 
   /**
    * @return This instance serialized as protobuf w/ a magic pb prefix.
-   * @see #parseFrom(byte[]);
+   * @see #parseFrom(byte[])
    */
   public byte [] toByteArray() {
     byte [] bytes = convert().toByteArray();
@@ -924,7 +924,7 @@ public class HRegionInfo implements Comparable<HRegionInfo> {
   /**
    * @param bytes
    * @return A deserialized {@link HRegionInfo} or null if we failed deserialize or passed bytes null
-   * @see {@link #toByteArray()}
+   * @see #toByteArray()
    */
   public static HRegionInfo parseFromOrNull(final byte [] bytes) {
     if (bytes == null || bytes.length <= 0) return null;
@@ -939,7 +939,7 @@ public class HRegionInfo implements Comparable<HRegionInfo> {
    * @param bytes A pb RegionInfo serialized with a pb magic prefix.
    * @return A deserialized {@link HRegionInfo}
    * @throws DeserializationException
-   * @see {@link #toByteArray()}
+   * @see #toByteArray()
    */
   public static HRegionInfo parseFrom(final byte [] bytes) throws DeserializationException {
     if (ProtobufUtil.isPBMagicPrefix(bytes)) {
@@ -967,7 +967,7 @@ public class HRegionInfo implements Comparable<HRegionInfo> {
    * the pb mergeDelimitedFrom (w/o the delimiter, pb reads to EOF which may not be what you want).
    * @return This instance serialized as a delimited protobuf w/ a magic pb prefix.
    * @throws IOException
-   * @see {@link #toByteArray()}
+   * @see #toByteArray()
    */
   public byte [] toDelimitedByteArray() throws IOException {
     return ProtobufUtil.toDelimitedByteArray(convert());
@@ -1096,7 +1096,7 @@ public class HRegionInfo implements Comparable<HRegionInfo> {
    * @param infos HRegionInfo objects to serialize
    * @return This instance serialized as a delimited protobuf w/ a magic pb prefix.
    * @throws IOException
-   * @see {@link #toByteArray()}
+   * @see #toByteArray()
    */
   public static byte[] toDelimitedByteArray(HRegionInfo... infos) throws IOException {
     byte[][] bytes = new byte[infos.length][];

hbase-server/src/main/java/org/apache/hadoop/hbase/HServerInfo.java

@@ -33,11 +33,11 @@ import org.apache.hadoop.io.WritableComparable;
  * {@link HServerAddress}, its webui port, and its server startcode.  It was
  * used to pass meta info about a server across an RPC but we've since made
  * it so regionserver info is up in ZooKeeper and so this class is on its
- * way out. It used to carry {@link HServerLoad} but as off HBase 0.92.0, the
+ * way out. It used to carry HServerLoad but as off HBase 0.92.0, the
  * HServerLoad is passed independent of this class. Also, we now no longer pass
  * the webui from regionserver to master (TODO: Fix).
  * @deprecated Use {@link InetSocketAddress} and or {@link ServerName} and or
- * {@link HServerLoad}
+ * HServerLoad
  */
 public class HServerInfo extends VersionedWritable
 implements WritableComparable<HServerInfo> {

hbase-server/src/main/java/org/apache/hadoop/hbase/HTableDescriptor.java

@@ -899,7 +899,7 @@ public class HTableDescriptor implements WritableComparable<HTableDescriptor> {
   /**
    * <em> INTERNAL </em> This method is a part of {@link WritableComparable} interface 
    * and is used for serialization of the HTableDescriptor over RPC
-   * @deprecated Writables are going away.  Use pb {@link #toByteArray()(byte[])} instead.
+   * @deprecated Writables are going away.  Use pb {@link #toByteArray(byte[])} instead.
    */
   @Deprecated
   @Override
@@ -1231,7 +1231,7 @@ public class HTableDescriptor implements WritableComparable<HTableDescriptor> {
 
   /**
    * @return This instance serialized with pb with pb magic prefix
-   * @see {@link #parseFrom(byte[])}
+   * @see #parseFrom(byte[])
    */
   public byte [] toByteArray() {
     return ProtobufUtil.prependPBMagic(convert().toByteArray());
@@ -1242,7 +1242,7 @@ public class HTableDescriptor implements WritableComparable<HTableDescriptor> {
    * @return An instance of {@link HTableDescriptor} made from <code>bytes</code>
    * @throws DeserializationException
    * @throws IOException 
-   * @see {@link #toByteArray()}
+   * @see #toByteArray()
    */
   public static HTableDescriptor parseFrom(final byte [] bytes)
   throws DeserializationException, IOException {

hbase-server/src/main/java/org/apache/hadoop/hbase/MasterAdminProtocol.java

@@ -153,7 +153,7 @@ public interface MasterAdminProtocol extends
   /**
    * Unassign a region from current hosting regionserver.  Region will then be
    * assigned to a regionserver chosen at random.  Region could be reassigned
-   * back to the same server.  Use {@link #moveRegion(RpcController,MoveRegionRequest}
+   * back to the same server.  Use {@link #moveRegion(RpcController,MoveRegionRequest)}
    * if you want to control the region movement.
    * @param controller Unused (set to null).
    * @param req The request that contains:<br>

hbase-server/src/main/java/org/apache/hadoop/hbase/RegionTransition.java

@@ -31,7 +31,7 @@ import com.google.protobuf.InvalidProtocolBufferException;
  * Current state of a region in transition.  Holds state of a region as it moves through the
  * steps that take it from offline to open, etc.  Used by regionserver, master, and zk packages.
  * Encapsulates protobuf serialization/deserialization so we don't leak generated pb outside this
- * class.  Create an instance using {@link #createRegionTransition(EventType, byte[], ServerName)}.
+ * class.  Create an instance using createRegionTransition(EventType, byte[], ServerName).
  * <p>Immutable
  */
 @InterfaceAudience.Private
@@ -85,7 +85,6 @@ public class RegionTransition {
    * @param regionName
    * @param sn
    * @return a serialized pb {@link RegionTransition}
-   * @see #parseRegionTransition(byte[])
    */
   public static RegionTransition createRegionTransition(final EventType type,
       final byte [] regionName, final ServerName sn) {
@@ -98,7 +97,6 @@ public class RegionTransition {
    * @param sn
    * @param payload May be null
    * @return a serialized pb {@link RegionTransition}
-   * @see #parseRegionTransition(byte[])
    */
   public static RegionTransition createRegionTransition(final EventType type,
       final byte [] regionName, final ServerName sn, final byte [] payload) {

hbase-server/src/main/java/org/apache/hadoop/hbase/client/HBaseAdmin.java

@@ -458,7 +458,7 @@ public class HBaseAdmin implements Abortable, Closeable {
   /**
    * Creates a new table but does not block and wait for it to come online.
    * Asynchronous operation.  To check if the table exists, use
-   * {@link: #isTableAvailable} -- it is not safe to create an HTable
+   * {@link: #isTableAvailable()} -- it is not safe to create an HTable
    * instance to this table before it is available.
    * Note : Avoid passing empty split key.
    * @param desc table descriptor for table

hbase-server/src/main/java/org/apache/hadoop/hbase/client/HConnection.java

@@ -252,7 +252,6 @@ public interface HConnection extends Abortable, Closeable {
    * @return an object of type T
    * @throws IOException if a remote or network exception occurs
    * @throws RuntimeException other unspecified error
-   * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)}
    */
   @Deprecated
   public <T> T getRegionServerWithRetries(ServerCallable<T> callable)
@@ -266,7 +265,6 @@ public interface HConnection extends Abortable, Closeable {
    * @return an object of type T
    * @throws IOException if a remote or network exception occurs
    * @throws RuntimeException other unspecified error
-   * @deprecated Use {@link HConnectionManager#withoutRetries(ServerCallable)}
    */
   @Deprecated
   public <T> T getRegionServerWithoutRetries(ServerCallable<T> callable)