[
https://issues.apache.org/jira/browse/BEAM-6679?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Etienne Chauchot updated BEAM-6679:
-----------------------------------
Description:
The combination of `<pre>` for preserving line breaks and `{@code` for
preserving angle brackets and curly brackets _mostly_ works.
`@` is the problematic character. I see `\{@literal @}` show up in many
classes' Javadoc, and that method doesn't do what's intended. In current Java 8
builds, it looks like `@` inside `\{@code}` is not a problem in the general
case and doesn't need to be escaped. The one exception is when `@` is the first
non-whitespace character in a line, in which case it appears that Javadoc
thinks it's a tag like `@return` or `@param` and throws an error.
The solution here is to end the `@code` block and start a new one on the line
that contains '@' litteral. 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 next block
was:
[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.
> Fix javadoc @ litterals
> -----------------------
>
> 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: 1h 20m
> Remaining Estimate: 0h
>
> The combination of `<pre>` for preserving line breaks and `{@code` for
> preserving angle brackets and curly brackets _mostly_ works.
> `@` is the problematic character. I see `\{@literal @}` show up in many
> classes' Javadoc, and that method doesn't do what's intended. In current Java
> 8 builds, it looks like `@` inside `\{@code}` is not a problem in the general
> case and doesn't need to be escaped. The one exception is when `@` is the
> first non-whitespace character in a line, in which case it appears that
> Javadoc thinks it's a tag like `@return` or `@param` and throws an error.
> The solution here is to end the `@code` block and start a new one on the line
> that contains '@' litteral. 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 next block
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
