mjsax commented on code in PR #18703:
URL: https://github.com/apache/kafka/pull/18703#discussion_r1929508924
##########
streams/src/main/java/org/apache/kafka/streams/kstream/KStream.java:
##########
@@ -62,92 +62,59 @@ public interface KStream<K, V> {
/**
* Create a new {@code KStream} that consists of all records of this
stream which satisfy the given predicate.
* All records that do not satisfy the predicate are dropped.
- * This is a stateless record-by-record operation.
+ * This is a stateless record-by-record operation (cf. {@link
#processValues(FixedKeyProcessorSupplier, String...)}
+ * for stateful record processing).
+ *
+ * @param predicate
+ * a filter {@link Predicate} that is applied to each record
+ *
+ * @return A {@code KStream} that contains only those records that satisfy
the given predicate.
*
- * @param predicate a filter {@link Predicate} that is applied to each
record
- * @return a {@code KStream} that contains only those records that satisfy
the given predicate
* @see #filterNot(Predicate)
*/
KStream<K, V> filter(final Predicate<? super K, ? super V> predicate);
/**
- * Create a new {@code KStream} that consists of all records of this
stream which satisfy the given predicate.
- * All records that do not satisfy the predicate are dropped.
- * This is a stateless record-by-record operation.
+ * See {@link #filter(Predicate)}.
Review Comment:
We have a lot of repetition in the JavaDocs, which lead to inconsistencies.
For the simple method updated in this PR, it's not a real problem, but for the
ones with longer JavaDoc is really difficult to keep all overloads in-sync.
Thus, I think it's better to change the pattern, and have extensive JavaDocs
only on one overload, and link to it from the other overloads.
Applying this pattern also to simple methods for concistency.
##########
streams/src/main/java/org/apache/kafka/streams/kstream/KStream.java:
##########
@@ -62,92 +62,59 @@ public interface KStream<K, V> {
/**
* Create a new {@code KStream} that consists of all records of this
stream which satisfy the given predicate.
* All records that do not satisfy the predicate are dropped.
- * This is a stateless record-by-record operation.
+ * This is a stateless record-by-record operation (cf. {@link
#processValues(FixedKeyProcessorSupplier, String...)}
+ * for stateful record processing).
+ *
+ * @param predicate
+ * a filter {@link Predicate} that is applied to each record
+ *
+ * @return A {@code KStream} that contains only those records that satisfy
the given predicate.
*
- * @param predicate a filter {@link Predicate} that is applied to each
record
- * @return a {@code KStream} that contains only those records that satisfy
the given predicate
* @see #filterNot(Predicate)
*/
KStream<K, V> filter(final Predicate<? super K, ? super V> predicate);
/**
- * Create a new {@code KStream} that consists of all records of this
stream which satisfy the given predicate.
- * All records that do not satisfy the predicate are dropped.
- * This is a stateless record-by-record operation.
+ * See {@link #filter(Predicate)}.
Review Comment:
We have a lot of repetition in the JavaDocs, which lead to inconsistencies.
For the simple method updated in this PR, it's not a real problem, but for the
ones with longer JavaDoc is really difficult to keep all overloads in-sync.
Thus, I think it's better to change the pattern, and have extensive JavaDocs
only on one overload, and link to it from the other overloads.
Applying this pattern also to simple methods for consistency.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: jira-unsubscr...@kafka.apache.org
For queries about this service, please contact Infrastructure at:
us...@infra.apache.org
