MINOR: cleanup JavaDocs for deprecation warnings (#18402)

Reviewers: Bill Bejeck <bbejeck@gmail.com>, Chia-Ping Tsai <chia7712@gmail.com>

clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupDescription.java

@@ -47,7 +47,7 @@ public class ConsumerGroupDescription {
     private final Optional<Integer> targetAssignmentEpoch;
 
     /**
-     * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)}.
+     * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)} instead.
      */
     @Deprecated
     public ConsumerGroupDescription(String groupId,
@@ -60,7 +60,7 @@ public class ConsumerGroupDescription {
     }
 
     /**
-     * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)}.
+     * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)} instead.
      */
     @Deprecated
     public ConsumerGroupDescription(String groupId,
@@ -74,7 +74,7 @@ public class ConsumerGroupDescription {
     }
 
     /**
-     * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)}.
+     * @deprecated Since 4.0. Use {@link #ConsumerGroupDescription(String, boolean, Collection, String, GroupType, GroupState, Node, Set, Optional, Optional)} instead.
      */
     @Deprecated
     public ConsumerGroupDescription(String groupId,

clients/src/main/java/org/apache/kafka/clients/admin/ConsumerGroupListing.java

@@ -49,7 +49,7 @@ public class ConsumerGroupListing {
      * @param groupId                   Group Id.
      * @param isSimpleConsumerGroup     If consumer group is simple or not.
      * @param state                     The state of the consumer group.
-     * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, boolean)}.
+     * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, boolean)} instead.
      */
     @Deprecated
     public ConsumerGroupListing(String groupId, boolean isSimpleConsumerGroup, Optional<ConsumerGroupState> state) {
@@ -63,7 +63,7 @@ public class ConsumerGroupListing {
      * @param isSimpleConsumerGroup     If consumer group is simple or not.
      * @param state                     The state of the consumer group.
      * @param type                      The type of the consumer group.
-     * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, Optional, boolean)}.
+     * @deprecated Since 4.0. Use {@link #ConsumerGroupListing(String, Optional, Optional, boolean)} instead.
      */
     @Deprecated
     public ConsumerGroupListing(
@@ -133,7 +133,7 @@ public class ConsumerGroupListing {
 
     /**
      * Consumer Group state
-     * @deprecated Since 4.0. Use {@link #groupState()}.
+     * @deprecated Since 4.0. Use {@link #groupState()} instead.
      */
     @Deprecated
     public Optional<ConsumerGroupState> state() {

clients/src/main/java/org/apache/kafka/clients/admin/CreateDelegationTokenOptions.java

@@ -54,7 +54,7 @@ public class CreateDelegationTokenOptions extends AbstractOptions<CreateDelegati
     }
 
     /**
-     * @deprecated since 4.0 and should not be used any longer.
+     * @deprecated Since 4.0 and should not be used any longer.
      */
     @Deprecated
     public CreateDelegationTokenOptions maxlifeTimeMs(long maxLifetimeMs) {
@@ -68,7 +68,7 @@ public class CreateDelegationTokenOptions extends AbstractOptions<CreateDelegati
     }
 
     /**
-     * @deprecated since 4.0 and should not be used any longer.
+     * @deprecated Since 4.0 and should not be used any longer.
      */
     @Deprecated
     public long maxlifeTimeMs() {

clients/src/main/java/org/apache/kafka/clients/admin/ListConsumerGroupsOptions.java

@@ -52,7 +52,7 @@ public class ListConsumerGroupsOptions extends AbstractOptions<ListConsumerGroup
      * If states is set, only groups in these states will be returned by listConsumerGroups().
      * Otherwise, all groups are returned.
      * This operation is supported by brokers with version 2.6.0 or later.
-     * @deprecated Since 4.0. Use {@link #inGroupStates(Set)}.
+     * @deprecated Since 4.0. Use {@link #inGroupStates(Set)} instead.
      */
     @Deprecated
     public ListConsumerGroupsOptions inStates(Set<ConsumerGroupState> states) {
@@ -80,7 +80,7 @@ public class ListConsumerGroupsOptions extends AbstractOptions<ListConsumerGroup
 
     /**
      * Returns the list of States that are requested or empty if no states have been specified.
-     * @deprecated Since 4.0. Use {@link #inGroupStates(Set)}.
+     * @deprecated Since 4.0. Use {@link #inGroupStates(Set)} instead.
      */
     @Deprecated
     public Set<ConsumerGroupState> states() {

clients/src/main/java/org/apache/kafka/clients/admin/MemberDescription.java

@@ -57,7 +57,7 @@ public class MemberDescription {
     }
 
     /**
-     * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)}.
+     * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)} instead.
      */
     @Deprecated
     public MemberDescription(
@@ -81,7 +81,7 @@ public class MemberDescription {
     }
 
     /**
-     * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)}.
+     * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)} instead.
      */
     @Deprecated
     public MemberDescription(
@@ -102,7 +102,7 @@ public class MemberDescription {
     }
 
     /**
-     * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)}.
+     * @deprecated Since 4.0. Use {@link #MemberDescription(String, Optional, String, String, MemberAssignment, Optional, Optional, Optional)} instead.
      */
     @Deprecated
     public MemberDescription(String memberId,

clients/src/main/java/org/apache/kafka/clients/consumer/ConsumerRecords.java

@@ -37,6 +37,9 @@ public class ConsumerRecords<K, V> implements Iterable<ConsumerRecord<K, V>> {
     private final Map<TopicPartition, List<ConsumerRecord<K, V>>> records;
     private final Map<TopicPartition, OffsetAndMetadata> nextOffsets;
 
+    /**
+     * @deprecated Since 4.0. Use {@link #ConsumerRecords(Map, Map)} instead.
+     */
     @Deprecated
     public ConsumerRecords(Map<TopicPartition, List<ConsumerRecord<K, V>>> records) {
         this(records, Map.of());

clients/src/main/java/org/apache/kafka/clients/consumer/MockConsumer.java

@@ -82,7 +82,7 @@ public class MockConsumer<K, V> implements Consumer<K, V> {
     private final List<KafkaMetric> addedMetrics = new ArrayList<>();
 
     /**
-     * @deprecated Since 4.0. Use {@link #MockConsumer(String)}.
+     * @deprecated Since 4.0. Use {@link #MockConsumer(String)} instead.
      */
     @Deprecated
     public MockConsumer(OffsetResetStrategy offsetResetStrategy) {

clients/src/main/java/org/apache/kafka/clients/consumer/OffsetResetStrategy.java

@@ -19,7 +19,7 @@ package org.apache.kafka.clients.consumer;
 import java.util.Locale;
 
 /**
- * @deprecated Since 4.0. Use {@link org.apache.kafka.clients.consumer.internals.AutoOffsetResetStrategy instead.}
+ * @deprecated Since 4.0. Use {@link org.apache.kafka.clients.consumer.internals.AutoOffsetResetStrategy} instead.
  */
 @Deprecated
 public enum OffsetResetStrategy {

clients/src/main/java/org/apache/kafka/common/errors/RecordDeserializationException.java

@@ -45,6 +45,9 @@ public class RecordDeserializationException extends SerializationException {
     private final ByteBuffer valueBuffer;
     private final Headers headers;
 
+    /**
+     * @deprecated Since 3.9. Use {@link #RecordDeserializationException(DeserializationExceptionOrigin, TopicPartition, long, long, TimestampType, ByteBuffer, ByteBuffer, Headers, String, Throwable)} instead.
+     */
     @Deprecated
     public RecordDeserializationException(TopicPartition partition,
                                           long offset,

streams/src/main/java/org/apache/kafka/streams/StreamsConfig.java

@@ -165,6 +165,7 @@ public class StreamsConfig extends AbstractConfig {
     @Deprecated
     @SuppressWarnings("unused")
     public static final int DUMMY_THREAD_INDEX = 1;
+
     public static final long MAX_TASK_IDLE_MS_DISABLED = -1;
 
     // We impose these limitations because client tags are encoded into the subscription info,
@@ -486,7 +487,7 @@ public class StreamsConfig extends AbstractConfig {
     private static final String BUILT_IN_METRICS_VERSION_DOC = "Version of the built-in metrics to use.";
 
     /** {@code cache.max.bytes.buffering}
-     * @deprecated since 3.4.0 Use {@link #STATESTORE_CACHE_MAX_BYTES_CONFIG "statestore.cache.max.bytes"} instead. */
+     * @deprecated Since 3.4. Use {@link #STATESTORE_CACHE_MAX_BYTES_CONFIG "statestore.cache.max.bytes"} instead. */
     @SuppressWarnings("WeakerAccess")
     @Deprecated
     public static final String CACHE_MAX_BYTES_BUFFERING_CONFIG = "cache.max.bytes.buffering";
@@ -520,7 +521,7 @@ public class StreamsConfig extends AbstractConfig {
 
     /**
      * {@code default.deserialization.exception.handler}
-     * @deprecated since 4.0; use {@link #DESERIALIZATION_EXCEPTION_HANDLER_CLASS_CONFIG} instead
+     * @deprecated Since 4.0. Use {@link #DESERIALIZATION_EXCEPTION_HANDLER_CLASS_CONFIG} instead.
      */
     @SuppressWarnings("WeakerAccess")
     @Deprecated
@@ -535,7 +536,7 @@ public class StreamsConfig extends AbstractConfig {
 
     /**
      * {@code default.production.exception.handler}
-     * @deprecated since 4.0; Use {@link #PRODUCTION_EXCEPTION_HANDLER_CLASS_CONFIG} instead
+     * @deprecated Since 4.0. Use {@link #PRODUCTION_EXCEPTION_HANDLER_CLASS_CONFIG} instead.
      */
     @SuppressWarnings("WeakerAccess")
     @Deprecated
@@ -546,7 +547,10 @@ public class StreamsConfig extends AbstractConfig {
     public static final String PRODUCTION_EXCEPTION_HANDLER_CLASS_CONFIG = "production.exception.handler";
     private static final String PRODUCTION_EXCEPTION_HANDLER_CLASS_DOC = "Exception handling class that implements the <code>org.apache.kafka.streams.errors.ProductionExceptionHandler</code> interface.";
 
-    /** {@code default.dsl.store} */
+    /**
+     * {@code default.dsl.store}
+     * @deprecated Since 3.7. Use {@link #DSL_STORE_SUPPLIERS_CLASS_CONFIG} instead.
+     */
     @Deprecated
     @SuppressWarnings("WeakerAccess")
     public static final String DEFAULT_DSL_STORE_CONFIG = "default.dsl.store";
@@ -2021,7 +2025,7 @@ public class StreamsConfig extends AbstractConfig {
     }
 
     /**
-     * @deprecated since kafka 4.0; use {@link #deserializationExceptionHandler()} instead
+     * @deprecated Since 4.0. Use {@link #deserializationExceptionHandler()} instead.
      */
     @Deprecated
     @SuppressWarnings("WeakerAccess")
@@ -2043,7 +2047,7 @@ public class StreamsConfig extends AbstractConfig {
     }
 
     /**
-     * @deprecated since kafka 4.0; use {@link #productionExceptionHandler()} instead
+     * @deprecated Since 4.0. Use {@link #productionExceptionHandler()} instead.
      */
     @Deprecated
     @SuppressWarnings("WeakerAccess")

streams/src/main/java/org/apache/kafka/streams/errors/DefaultProductionExceptionHandler.java

@@ -26,6 +26,9 @@ import java.util.Map;
  * happens while attempting to produce result records.
  */
 public class DefaultProductionExceptionHandler implements ProductionExceptionHandler {
+    /**
+     * @deprecated Since 3.9. Use {@link #handle(ErrorHandlerContext, ProducerRecord, Exception)} instead.
+     */
     @SuppressWarnings("deprecation")
     @Deprecated
     @Override

streams/src/main/java/org/apache/kafka/streams/errors/LogAndContinueExceptionHandler.java

@@ -31,6 +31,9 @@ import java.util.Map;
 public class LogAndContinueExceptionHandler implements DeserializationExceptionHandler {
     private static final Logger log = LoggerFactory.getLogger(LogAndContinueExceptionHandler.class);
 
+    /**
+     * @deprecated Since 3.9. Use {@link #handle(ErrorHandlerContext, ConsumerRecord, Exception)} instead.
+     */
     @SuppressWarnings("deprecation")
     @Deprecated
     @Override

streams/src/main/java/org/apache/kafka/streams/errors/LogAndFailExceptionHandler.java

@@ -31,6 +31,9 @@ import java.util.Map;
 public class LogAndFailExceptionHandler implements DeserializationExceptionHandler {
     private static final Logger log = LoggerFactory.getLogger(LogAndFailExceptionHandler.class);
 
+    /**
+     * @deprecated Since 3.9. Use {@link #handle(ErrorHandlerContext, ConsumerRecord, Exception)} instead.
+     */
     @SuppressWarnings("deprecation")
     @Deprecated
     @Override

streams/src/main/java/org/apache/kafka/streams/kstream/ForeachProcessor.java

@@ -20,7 +20,7 @@ import org.apache.kafka.streams.processor.api.Processor;
 import org.apache.kafka.streams.processor.api.Record;
 
 /**
- * @deprecated since 4.0 and should not be used any longer.
+ * @deprecated Since 4.0 and should not be used any longer.
  */
 @Deprecated
 public class ForeachProcessor<K, V> implements Processor<K, V, Void, Void> {

streams/src/main/java/org/apache/kafka/streams/kstream/JoinWindows.java

@@ -154,7 +154,7 @@ public class JoinWindows extends Windows<Window> {
      * @param timeDifference join window interval
      * @return a new JoinWindows object with the window definition with and grace period (default to 24 hours minus {@code timeDifference})
      * @throws IllegalArgumentException if {@code timeDifference} is negative or can't be represented as {@code long milliseconds}
-     * @deprecated since 3.0. Use {@link #ofTimeDifferenceWithNoGrace(Duration)}} instead
+     * @deprecated Since 3.0. Use {@link #ofTimeDifferenceWithNoGrace(Duration)}} instead.
      */
     @Deprecated
     public static JoinWindows of(final Duration timeDifference) throws IllegalArgumentException {
@@ -221,7 +221,7 @@ public class JoinWindows extends Windows<Window> {
      * @return this updated builder
      * @throws IllegalArgumentException if the {@code afterWindowEnd} is negative or can't be represented as {@code long milliseconds}
      * @throws IllegalStateException if {@link #grace(Duration)} is called after {@link #ofTimeDifferenceAndGrace(Duration, Duration)} or {@link #ofTimeDifferenceWithNoGrace(Duration)}
-     * @deprecated since 3.0. Use {@link #ofTimeDifferenceAndGrace(Duration, Duration)} instead
+     * @deprecated Since 3.0. Use {@link #ofTimeDifferenceAndGrace(Duration, Duration)} instead.
      */
     @Deprecated
     public JoinWindows grace(final Duration afterWindowEnd) throws IllegalArgumentException {

streams/src/main/java/org/apache/kafka/streams/kstream/Joined.java

@@ -273,7 +273,7 @@ public class Joined<K, VLeft, VRight> implements NamedOperation<Joined<K, VLeft,
 
 
     /**
-     * @deprecated since 4.0 and should not be used any longer.
+     * @deprecated Since 4.0 and should not be used any longer.
      */
     @Deprecated
     public Duration gracePeriod() {
@@ -281,7 +281,7 @@ public class Joined<K, VLeft, VRight> implements NamedOperation<Joined<K, VLeft,
     }
 
     /**
-     * @deprecated since 4.0 and should not be used any longer.
+     * @deprecated Since 4.0 and should not be used any longer.
      */
     @Deprecated
     public Serde<K> keySerde() {
@@ -289,7 +289,7 @@ public class Joined<K, VLeft, VRight> implements NamedOperation<Joined<K, VLeft,
     }
 
     /**
-     * @deprecated since 4.0 and should not be used any longer.
+     * @deprecated Since 4.0 and should not be used any longer.
      */
     @Deprecated
     public Serde<VLeft> valueSerde() {
@@ -297,7 +297,7 @@ public class Joined<K, VLeft, VRight> implements NamedOperation<Joined<K, VLeft,
     }
 
     /**
-     * @deprecated since 4.0 and should not be used any longer.
+     * @deprecated Since 4.0 and should not be used any longer.
      */
     @Deprecated
     public Serde<VRight> otherValueSerde() {

tools/src/main/java/org/apache/kafka/tools/TopicCommand.java

@@ -709,7 +709,7 @@ public abstract class TopicCommand {
         private final ArgumentAcceptingOptionSpec<String> configOpt;
 
         /**
-         * @deprecated since 4.0 and should not be used any longer.
+         * @deprecated Since 4.0 and should not be used any longer.
          */
         @Deprecated
         private final ArgumentAcceptingOptionSpec<String> deleteConfigOpt;