mjsax commented on code in PR #18703:
URL: https://github.com/apache/kafka/pull/18703#discussion_r1936005098
##########
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.
Review Comment:
Well, looking at how JavaDocs are actually rendered, it seems to be better
to use capitalization and period. After `Returns:` there is a new line -- it's
weird if it start with lower case IMHO. Also, we sometime use more than one
sentence to describe what is returned, and it make it quite weird if we don't
use capitalization and periods if it's two sentences.
For (method and type/generic) parameters, given the rendering as single line
as `<name> - <description>` with a dash in between, I think the recommendation
does make sense though (even if using capitalization and periods at the end
might still be ok.)
At least that's why I did it the way I did it. 🤷
--
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
