[
https://issues.apache.org/jira/browse/BEAM-6679?focusedWorklogId=199282&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-199282
]
ASF GitHub Bot logged work on BEAM-6679:
----------------------------------------
Author: ASF GitHub Bot
Created on: 15/Feb/19 15:21
Start Date: 15/Feb/19 15:21
Worklog Time Spent: 10m
Work Description: jklukas commented on pull request #7852: [BEAM-6679]
Clean up GroupIntoBatches Javadoc
URL: https://github.com/apache/beam/pull/7852#discussion_r257275084
##########
File path:
sdks/java/core/src/main/java/org/apache/beam/sdk/transforms/GroupIntoBatches.java
##########
@@ -48,25 +48,24 @@
* are output to the output {@link PCollection}.
*
* <p>Windows are preserved (batches contain elements from the same window).
Batches may contain
- * elements from more than one bundle
+ * elements from more than one bundle.
*
- * <p>Example (batch call a webservice and get return codes)
+ * <p>Example (batch call a webservice and get return codes):
*
* <pre>{@code
- * Pipeline pipeline = Pipeline.create(...);
- * ... // KV collection
- * long batchSize = 100L;
- * pipeline.apply(GroupIntoBatches.<String, String>ofSize(batchSize))
- * .setCoder(KvCoder.of(StringUtf8Coder.of(),
IterableCoder.of(StringUtf8Coder.of())))
- * .apply(ParDo.of(new DoFn<KV<String, Iterable<String>>, KV<String,
String>>() {
- * {@literal @}ProcessElement
- * public void processElement({@literal @}Element KV<String, Iterable<String>>
element,
- * OutputReceiver<KV<String, String>> r) {
- * r.output(KV.of(element.getKey(), callWebService(element.getValue())));
- * }
- * }));
- * pipeline.run();
- * }</pre>
+ * PCollection<KV<String, String>> input = ...;
+ * long batchSize = 100L;
+ * PCollection<KV<String, Iterable<String>>> batched = input
+ * .apply(GroupIntoBatches.<String, String>ofSize(batchSize))
+ * .setCoder(KvCoder.of(StringUtf8Coder.of(),
IterableCoder.of(StringUtf8Coder.of())))
+ * .apply(ParDo.of(new DoFn<KV<String, Iterable<String>>, KV<String,
String>>() }{
+ * {@code @ProcessElement
Review comment:
On this line, `@` would be the first non-whitespace character if we weren't
starting a new `@code` block, which would cause Javadoc to raise an error.
The solution here is to end the `@code` block and start a new one on this
line. Note that `@code` and `@literal` blocks, while they will render literal
curly brackets, expect curly brackets to be balanced. Thus, we have to end the
previous code block before the `{` that opens the `DoFn` body in our example.
Thus, line 61 here contains `}{` to end the code block and render a literal
unmatched `{`. Then, we start a new code block on this line and we close this
block on line 67 so that we can have a literal unmatched `}` closing the `DoFn`
body of the example.
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
Issue Time Tracking
-------------------
Worklog Id: (was: 199282)
Time Spent: 50m (was: 40m)
> Clean up GroupIntoBatches Javadoc
> ---------------------------------
>
> Key: BEAM-6679
> URL: https://issues.apache.org/jira/browse/BEAM-6679
> Project: Beam
> Issue Type: Bug
> Components: sdk-java-core
> Reporter: Jeff Klukas
> Assignee: Jeff Klukas
> Priority: Minor
> Time Spent: 50m
> Remaining Estimate: 0h
>
> [The current Javadoc for
> GroupIntoBatches|https://beam.apache.org/releases/javadoc/2.10.0/org/apache/beam/sdk/transforms/GroupIntoBatches.html]
> is strangely formatted, making it difficult to understand the code example
> and learn how to use the transform.
> The code example should also follow conventions from classes like MapElements
> where the code example assumes a PCollection of some type and demonstrates
> the output PCollection type after applying the transform.
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
