HBASE-22344 Documented the deprecation of public and limited private APIs (apache#208)

Signed-off-by: stack <stack@apache.org>

Author: HorizonNet

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

@@ -162,7 +162,10 @@ protected HColumnDescriptor(ModifyableColumnFamilyDescriptor delegate) {
    * name: i.e. 'printable' and ends in a ':' (Null passes are allowed because
    * <code>b</code> can be null when deserializing).  Cannot start with a '.'
    * either. Also Family can not be an empty value or equal "recovered.edits".
-   * @deprecated Use {@link ColumnFamilyDescriptorBuilder#isLegalColumnFamilyName(byte[])}.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@link ColumnFamilyDescriptorBuilder#isLegalColumnFamilyName(byte[])} instead.
+   * @see ColumnFamilyDescriptorBuilder#isLegalColumnFamilyName(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   public static byte [] isLegalFamilyName(final byte [] b) {

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

@@ -551,9 +551,11 @@ public int compareTo(final HTableDescriptor other) {
   /**
    * Returns an unmodifiable collection of all the {@link HColumnDescriptor}
    * of all the column families of the table.
-   * @deprecated Use {@link #getColumnFamilies}.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #getColumnFamilies()} instead.
    * @return Immutable collection of {@link HColumnDescriptor} of all the
    * column families.
+   * @see #getColumnFamilies()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   public Collection<HColumnDescriptor> getFamilies() {
@@ -660,8 +662,9 @@ public int getColumnFamilyCount() {
    * of the table.
    *
    * @return Array of all the HColumnDescriptors of the current table
-   *
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
    * @see #getFamilies()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   @Override
@@ -677,7 +680,10 @@ public HColumnDescriptor[] getColumnFamilies() {
    * @param column Column family name
    * @return Column descriptor for the passed family name or the family on
    * passed in column.
-   * @deprecated Use {@link #getColumnFamily(byte[])}.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #getColumnFamily(byte[])}
+   *   instead.
+   * @see #getColumnFamily(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-18008">HBASE-18008</a>
    */
   @Deprecated
   public HColumnDescriptor getFamily(final byte[] column) {
@@ -800,19 +806,31 @@ public void removeCoprocessor(String className) {
   public static final HTableDescriptor NAMESPACE_TABLEDESC
     = new HTableDescriptor(TableDescriptorBuilder.NAMESPACE_TABLEDESC);
 
+  /**
+   * @deprecated since 0.94.1
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-6188">HBASE-6188</a>
+   */
   @Deprecated
   public HTableDescriptor setOwner(User owner) {
     getDelegateeForModification().setOwner(owner);
     return this;
   }
 
+  /**
+   * @deprecated since 0.94.1
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-6188">HBASE-6188</a>
+   */
   // used by admin.rb:alter(table_name,*args) to update owner.
   @Deprecated
   public HTableDescriptor setOwnerString(String ownerString) {
     getDelegateeForModification().setOwnerString(ownerString);
     return this;
   }
 
+  /**
+   * @deprecated since 0.94.1
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-6188">HBASE-6188</a>
+   */
   @Override
   @Deprecated
   public String getOwnerString() {

hbase-client/src/main/java/org/apache/hadoop/hbase/client/Admin.java

@@ -1726,9 +1726,11 @@ HTableDescriptor[] getTableDescriptors(List<String> names)
    * Do not use. Usually it is ignored but if not, it can do more damage than good. See hbck2.
    * @param procId ID of the procedure to abort
    * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
-   * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does not exist
-   * @throws IOException
-   * @deprecated Since 2.1.1 -- to be removed.
+   * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does
+   *         not exist
+   * @throws IOException if a remote or network exception occurs
+   * @deprecated since 2.1.1 and will be removed in 4.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
    */
   @Deprecated
   boolean abortProcedure(
@@ -1746,8 +1748,9 @@ boolean abortProcedure(
    * @param procId ID of the procedure to abort
    * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
    * @return <code>true</code> if aborted, <code>false</code> if procedure already completed or does not exist
-   * @throws IOException
-   * @deprecated Since 2.1.1 -- to be removed.
+   * @throws IOException if a remote or network exception occurs
+   * @deprecated since 2.1.1 and will be removed in 4.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
    */
   @Deprecated
   Future<Boolean> abortProcedureAsync(

hbase-client/src/main/java/org/apache/hadoop/hbase/client/AsyncAdmin.java

@@ -864,7 +864,8 @@ CompletableFuture<Boolean> isProcedureFinished(String signature, String instance
    * @param mayInterruptIfRunning if the proc completed at least one step, should it be aborted?
    * @return true if aborted, false if procedure already completed or does not exist. the value is
    *         wrapped by {@link CompletableFuture}
-   * @deprecated Since 2.1.1 -- to be removed.
+   * @deprecated since 2.1.1 and will be removed in 4.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-21223">HBASE-21223</a>
    */
   @Deprecated
   CompletableFuture<Boolean> abortProcedure(long procId, boolean mayInterruptIfRunning);

hbase-client/src/main/java/org/apache/hadoop/hbase/client/Scan.java

@@ -196,7 +196,9 @@ public class Scan extends Query {
   public Scan() {}
 
   /**
-   * @deprecated use {@code new Scan().withStartRow(startRow).setFilter(filter)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@code new Scan().withStartRow(startRow).setFilter(filter)} instead.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan(byte[] startRow, Filter filter) {
@@ -210,7 +212,9 @@ public Scan(byte[] startRow, Filter filter) {
    * If the specified row does not exist, the Scanner will start from the next closest row after the
    * specified row.
    * @param startRow row to start scanner at or after
-   * @deprecated use {@code new Scan().withStartRow(startRow)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@code new Scan().withStartRow(startRow)} instead.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan(byte[] startRow) {
@@ -221,7 +225,9 @@ public Scan(byte[] startRow) {
    * Create a Scan operation for the range of rows specified.
    * @param startRow row to start scanner at or after (inclusive)
    * @param stopRow row to stop scanner before (exclusive)
-   * @deprecated use {@code new Scan().withStartRow(startRow).withStopRow(stopRow)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use
+   *   {@code new Scan().withStartRow(startRow).withStopRow(stopRow)} instead.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan(byte[] startRow, byte[] stopRow) {
@@ -423,8 +429,11 @@ public Scan setTimestamp(long timestamp) {
    * @return this
    * @throws IllegalArgumentException if startRow does not meet criteria for a row key (when length
    *           exceeds {@link HConstants#MAX_ROW_LENGTH})
-   * @deprecated use {@link #withStartRow(byte[])} instead. This method may change the inclusive of
-   *             the stop row to keep compatible with the old behavior.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #withStartRow(byte[])}
+   *   instead. This method may change the inclusive of the stop row to keep compatible with the old
+   *   behavior.
+   * @see #withStartRow(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan setStartRow(byte[] startRow) {
@@ -483,8 +492,11 @@ public Scan withStartRow(byte[] startRow, boolean inclusive) {
    * @return this
    * @throws IllegalArgumentException if stopRow does not meet criteria for a row key (when length
    *           exceeds {@link HConstants#MAX_ROW_LENGTH})
-   * @deprecated use {@link #withStopRow(byte[])} instead. This method may change the inclusive of
-   *             the stop row to keep compatible with the old behavior.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #withStopRow(byte[])} instead.
+   *   This method may change the inclusive of the stop row to keep compatible with the old
+   *   behavior.
+   * @see #withStopRow(byte[])
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17320">HBASE-17320</a>
    */
   @Deprecated
   public Scan setStopRow(byte[] stopRow) {
@@ -601,8 +613,10 @@ private byte[] calculateTheClosestNextRowKeyForPrefix(byte[] rowKeyPrefix) {
   /**
    * Get all available versions.
    * @return this
-   * @deprecated It is easy to misunderstand with column family's max versions, so use
-   *             {@link #readAllVersions()} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column
+   *   family's max versions, so use {@link #readAllVersions()} instead.
+   * @see #readAllVersions()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17125">HBASE-17125</a>
    */
   @Deprecated
   public Scan setMaxVersions() {
@@ -613,8 +627,10 @@ public Scan setMaxVersions() {
    * Get up to the specified number of versions of each column.
    * @param maxVersions maximum versions for each column
    * @return this
-   * @deprecated It is easy to misunderstand with column family's max versions, so use
-   *             {@link #readVersions(int)} instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. It is easy to misunderstand with column
+   *   family's max versions, so use {@link #readVersions(int)} instead.
+   * @see #readVersions(int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17125">HBASE-17125</a>
    */
   @Deprecated
   public Scan setMaxVersions(int maxVersions) {
@@ -1037,12 +1053,13 @@ public boolean isRaw() {
    * better performance for small scan. [HBASE-9488]. Generally, if the scan range is within one
    * data block(64KB), it could be considered as a small scan.
    * @param small
-   * @deprecated since 2.0.0. Use {@link #setLimit(int)} and {@link #setReadType(ReadType)} instead.
-   *             And for the one rpc optimization, now we will also fetch data when openScanner, and
-   *             if the number of rows reaches the limit then we will close the scanner
-   *             automatically which means we will fall back to one rpc.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #setLimit(int)} and
+   *   {@link #setReadType(ReadType)} instead. And for the one rpc optimization, now we will also
+   *   fetch data when openScanner, and if the number of rows reaches the limit then we will close
+   *   the scanner automatically which means we will fall back to one rpc.
    * @see #setLimit(int)
    * @see #setReadType(ReadType)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17045">HBASE-17045</a>
    */
   @Deprecated
   public Scan setSmall(boolean small) {
@@ -1054,7 +1071,9 @@ public Scan setSmall(boolean small) {
   /**
    * Get whether this scan is a small scan
    * @return true if small scan
-   * @deprecated since 2.0.0. See the comment of {@link #setSmall(boolean)}
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. See the comment of
+   *   {@link #setSmall(boolean)}
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-17045">HBASE-17045</a>
    */
   @Deprecated
   public boolean isSmall() {

hbase-client/src/main/java/org/apache/hadoop/hbase/client/SnapshotDescription.java

@@ -37,7 +37,10 @@ public SnapshotDescription(String name) {
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table) {
@@ -49,7 +52,10 @@ public SnapshotDescription(String name, TableName table) {
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName, SnapshotType)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table, SnapshotType type) {
@@ -61,7 +67,10 @@ public SnapshotDescription(String name, TableName table, SnapshotType type) {
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName, SnapshotType, String)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table, SnapshotType type, String owner) {
@@ -73,7 +82,10 @@ public SnapshotDescription(String name, TableName table, SnapshotType type, Stri
   }
 
   /**
-   * @deprecated Use the version with the TableName instance instead
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use the version with the TableName
+   *   instance instead.
+   * @see #SnapshotDescription(String, TableName, SnapshotType, String, long, int)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public SnapshotDescription(String name, String table, SnapshotType type, String owner,
@@ -96,7 +108,11 @@ public String getName() {
   }
 
   /**
-   * @deprecated Use getTableName() or getTableNameAsString() instead.
+   * @deprecated since 2.0.0 and will be removed in 3.0.0. Use {@link #getTableName()} or
+   *   {@link #getTableNameAsString()} instead.
+   * @see #getTableName()
+   * @see #getTableNameAsString()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-16892">HBASE-16892</a>
    */
   @Deprecated
   public String getTable() {

hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptor.java

@@ -191,6 +191,10 @@ default Collection<String> getCoprocessors() {
    */
   TableName getTableName();
 
+  /**
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+   */
   @Deprecated
   String getOwnerString();
 

hbase-client/src/main/java/org/apache/hadoop/hbase/client/TableDescriptorBuilder.java

@@ -452,12 +452,20 @@ public TableDescriptorBuilder setNormalizationEnabled(final boolean isEnable) {
     return this;
   }
 
+  /**
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+   */
   @Deprecated
   public TableDescriptorBuilder setOwner(User owner) {
     desc.setOwner(owner);
     return this;
   }
 
+  /**
+   * @deprecated since 2.0.0 and will be removed in 3.0.0.
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+   */
   @Deprecated
   public TableDescriptorBuilder setOwnerString(String ownerString) {
     desc.setOwnerString(ownerString);
@@ -1453,17 +1461,29 @@ public void removeCoprocessor(String className) {
       }
     }
 
+    /**
+     * @deprecated since 2.0.0 and will be removed in 3.0.0.
+     * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+     */
     @Deprecated
     public ModifyableTableDescriptor setOwner(User owner) {
       return setOwnerString(owner != null ? owner.getShortName() : null);
     }
 
+    /**
+     * @deprecated since 2.0.0 and will be removed in 3.0.0.
+     * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+     */
     // used by admin.rb:alter(table_name,*args) to update owner.
     @Deprecated
     public ModifyableTableDescriptor setOwnerString(String ownerString) {
       return setValue(OWNER_KEY, ownerString);
     }
 
+    /**
+     * @deprecated since 2.0.0 and will be removed in 3.0.0.
+     * @see <a href="https://issues.apache.org/jira/browse/HBASE-15583">HBASE-15583</a>
+     */
     @Override
     @Deprecated
     public String getOwnerString() {

hbase-client/src/main/java/org/apache/hadoop/hbase/filter/FirstKeyValueMatchingQualifiersFilter.java

@@ -43,7 +43,8 @@
  * caveat, this filter is only useful for special cases
  * like org.apache.hadoop.hbase.mapreduce.RowCounter.
  * <p>
- * @deprecated Deprecated in 2.0. See HBASE-13347
+ * @deprecated Deprecated in 2.0.0 and will be removed in 3.0.0.
+ * @see <a href="https://issues.apache.org/jira/browse/HBASE-13347">HBASE-13347</a>
  */
 @InterfaceAudience.Public
 @Deprecated

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

@@ -39,7 +39,9 @@ public class HBaseConfiguration extends Configuration {
   /**
    * Instantiating HBaseConfiguration() is deprecated. Please use
    * HBaseConfiguration#create() to construct a plain Configuration
-   * @deprecated Please use create() instead.
+   * @deprecated since 0.90.0. Please use {@link #create()} instead.
+   * @see #create()
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-2036">HBASE-2036</a>
    */
   @Deprecated
   public HBaseConfiguration() {
@@ -53,7 +55,9 @@ public HBaseConfiguration() {
   /**
    * Instantiating HBaseConfiguration() is deprecated. Please use
    * HBaseConfiguration#create(conf) to construct a plain Configuration
-   * @deprecated Please user create(conf) instead.
+   * @deprecated since 0.90.0. Please use {@link #create(Configuration)} instead.
+   * @see #create(Configuration)
+   * @see <a href="https://issues.apache.org/jira/browse/HBASE-2036">HBASE-2036</a>
    */
   @Deprecated
   public HBaseConfiguration(final Configuration c) {