[
https://issues.apache.org/jira/browse/BEAM-6679?focusedWorklogId=199404&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-199404
]
ASF GitHub Bot logged work on BEAM-6679:
----------------------------------------
Author: ASF GitHub Bot
Created on: 15/Feb/19 20:05
Start Date: 15/Feb/19 20:05
Worklog Time Spent: 10m
Work Description: jklukas commented on pull request #7855: [BEAM-6679]
Fix javadoc @ literals
URL: https://github.com/apache/beam/pull/7855
This change ensures that the core module javadoc:
./gradlew ':beam-sdks-java-core:javadoc'
no longer produces the string `@literal` anywhere in the produced html.
There may still be some instances in other modules.
Many code examples in the core SDK use `{@literal @}` inside of a `{@code}`
block, which does escape the `@` as expected, but rather produces the text
`{@literal @}`.
There's unfortunately not any single solution that's elegant in all cases.
The SDK already uses a variety of markup styles for code examples, and I expect
that to continue to be the case depending on the complexity of the example.
I've made additional whitespace fixes along with changing how `@literal` is
used such that each of these code examples now renders nicely with the current
Java 8 build.
------------------------
Thank you for your contribution! Follow this checklist to help us
incorporate your contribution quickly and easily:
- [ ] [**Choose
reviewer(s)**](https://beam.apache.org/contribute/#make-your-change) and
mention them in a comment (`R: @username`).
- [ ] Format the pull request title like `[BEAM-XXX] Fixes bug in
ApproximateQuantiles`, where you replace `BEAM-XXX` with the appropriate JIRA
issue, if applicable. This will automatically link the pull request to the
issue.
- [ ] If this contribution is large, please file an Apache [Individual
Contributor License Agreement](https://www.apache.org/licenses/icla.pdf).
Post-Commit Tests Status (on master branch)
------------------------------------------------------------------------------------------------
Lang | SDK | Apex | Dataflow | Flink | Gearpump | Samza | Spark
--- | --- | --- | --- | --- | --- | --- | ---
Go | [](https://builds.apache.org/job/beam_PostCommit_Go/lastCompletedBuild/)
| --- | --- | --- | --- | --- | ---
Java | [](https://builds.apache.org/job/beam_PostCommit_Java/lastCompletedBuild/)
| [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Apex/lastCompletedBuild/)
| [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Dataflow/lastCompletedBuild/)
| [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Flink/lastCompletedBuild/)<br>[](https://builds.apache.org/job/beam_PostCommit_Java_PVR_Flink_Batch/lastCompletedBuild/)<br>[](https://builds.apache.org/job/beam_PostCommit_Java_PVR_Flink_Streaming/lastCompletedBuild/)
| [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Gearpump/lastCompletedBuild/)
| [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Samza/lastCompletedBuild/)
| [](https://builds.apache.org/job/beam_PostCommit_Java_ValidatesRunner_Spark/lastCompletedBuild/)
Python | [](https://builds.apache.org/job/beam_PostCommit_Python_Verify/lastCompletedBuild/)
| --- | [](https://builds.apache.org/job/beam_PostCommit_Py_VR_Dataflow/lastCompletedBuild/)
</br> [](https://builds.apache.org/job/beam_PostCommit_Py_ValCont/lastCompletedBuild/)
| [](https://builds.apache.org/job/beam_PreCommit_Python_PVR_Flink_Cron/lastCompletedBuild/)
| --- | --- | ---
See [.test-infra/jenkins/README](../.test-infra/jenkins/README.md) for
trigger phrase, status and link of all Jenkins jobs.
----------------------------------------------------------------
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: 199404)
Time Spent: 1h 40m (was: 1.5h)
> 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 40m
> 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)
