Fix '@' character in javadoc code snippets

[pigelvy]

In the javadoc, the character '@' can be used directly in {@code …}. Using {@literal @} causes wrong formatting of the Java code snippets.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[pigelvy]

If I'm not mistaken about the proper formatting of code snippets, the syntax <pre>{@code …}</pre> should be applied to the javadoc of other annotations.
It should simplify the writting of Java code snippets by getting rid of {@Literal …}.

[eamonnmcmanus]

Javadoc has had a long-standing bug where a @ was interpreted as starting a tag if it was at the start of the line (after any initial *), even if the @ was inside a multiline {@code} or {@literal}. If we're able to determine that no version of Javadoc we use is affected by that bug anymore, we could potentially make simplifications like this one.

[cushon]

Javadoc has had a long-standing bug where a @ was interpreted as starting a tag if it was at the start of the line (after any initial *), even if the @ was inside a multiline {@code} or {@literal}. If we're able to determine that no version of Javadoc we use is affected by that bug anymore, we could potentially make simplifications like this one.

That was fixed in JDK 15 (https://bugs.openjdk.org/browse/JDK-8241780), and we use JDK 15 to generate javadoc for that reason (4f9e308), so it should be safe to make changes like this one at this point.

[cushon]

Javadoc has had a long-standing bug where a @ was interpreted as starting a tag if it was at the start of the line (after any initial *), even if the @ was inside a multiline {@code} or {@literal}. If we're able to determine that no version of Javadoc we use is affected by that bug anymore, we could potentially make simplifications like this one.

That was fixed in JDK 15 (https://bugs.openjdk.org/browse/JDK-8241780), and we use JDK 15 to generate javadoc for that reason (4f9e308), so it should be safe to make changes like this one at this point.

Er, looking at the failing CI, we still generating Javadoc for the entire matrix, and just using JDK 15 to publish it:

error-prone/.github/workflows/ci.yml

Lines 54 to 56 in 4137a98

	- name: 'Javadoc'
	shell: bash
	run: mvn -P '!examples' javadoc:aggregate

I don't mind letting it regress for JDK 11 at this point, but I'm not sure what the cleanest way to skip that in the matrix is.

[tbroyer]

I don't mind letting it regress for JDK 11 at this point, but I'm not sure what the cleanest way to skip that in the matrix is.

Maybe just add an if: to the step to only build (or skip) them on select JDK versions?
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsif

[cushon]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@pigelvy can you resolve this?

[pigelvy]

@cushon CLA signed. Sorry for the delay. It's my first time 😌