MINOR: Improve API docs of (flatT|t)ransform#6365
Conversation
This commit is a leftover of pull request apache#5273.
| * a schedule must be registered. | ||
| * The {@link Transformer} must return a {@link KeyValue} type in {@link Transformer#transform(Object, Object) | ||
| * transform()} and {@link org.apache.kafka.streams.processor.Punctuator#punctuate(long) punctuate()}. | ||
| * transform(K, V)} and {@link org.apache.kafka.streams.processor.Punctuator#punctuate(long) punctuate(long)}. |
There was a problem hiding this comment.
We don't add parameters in any JavaDocs. We use () in purpose to "shorten" long parameter lists (if usr follows the link, she sees the full parameter list). Note that
{@link org.apache.kafka.streams.processor.Punctuator#punctuate(long)}
and
{@link org.apache.kafka.streams.processor.Punctuator#punctuate(long) punctuate(long)}
would be the same (both render as punctuate(long)), but we want to get simplified punctuate().
Similar below.
There was a problem hiding this comment.
I removed the parameters from the links in the parts that I modified. However, in the other parts there are also links with parameters, e.g., line 544. Should I also change those in this PR?
There was a problem hiding this comment.
I was just looking across the JavaDocs. Seems we are not very consistent in what we do... L544 is not the only example. I leave it up to you if you want to clean it up, or not. We also just merge this PR as-is. Might not be worth the time?
There was a problem hiding this comment.
I removed the parameters from all the links to methods in the javadocs for transform and flatTransform.
Additionally, reformulated the part about type-safety at compile-time.
- removes more parameters from links in javadocs
mjsax
left a comment
mjsax
left a comment
There was a problem hiding this comment.
LGTM.
Call for second review (any of @guozhangwang @bbejeck @vvcephei @ableegoldman)
bbejeck
changed the title
This commit is a follow-up of pull request #5273 Reviewers: Matthias J. Sax <mjsax@apache.org>, Bill Bejeck <bbejeck@gmail.com>
This commit is a follow-up of pull request apache#5273 Reviewers: Matthias J. Sax <mjsax@apache.org>, Bill Bejeck <bbejeck@gmail.com>
3 participants
This commit is a follow-up of pull request #5273.
Committer Checklist (excluded from commit message)