UnescapedEntity support for @snippet javadoc tag

[ben-manes]

The {@snippet : ...} is the preferred replacement for <pre>{@code ...}</pre> code blocks. When mirroring the guava change I received the following warnings:

/Users/ben/projects/caffeine/caffeine/src/main/java/com/github/benmanes/caffeine/cache/Caffeine.java:73: warning: [UnescapedEntity] This looks like a type with type parameters. The < and > characters here will be interpreted as HTML, which can be avoided by wrapping it in a {@code } tag.
 *   LoadingCache<Key, Graph> graphs = Caffeine.newBuilder()
     ^
    (see https://errorprone.info/bugpattern/UnescapedEntity)
  Did you mean '*   {@code LoadingCache<Key, Graph>} graphs = Caffeine.newBuilder()'?

for the code,

 * {@snippet :
 *   LoadingCache<Key, Graph> graphs = Caffeine.newBuilder()
 *       .maximumSize(10_000)
 *       .expireAfterWrite(Duration.ofMinutes(10))
 *       .removalListener((Key key, Graph graph, RemovalCause cause) ->
 *           System.out.printf("Key %s was removed (%s)%n", key, cause))
 *       .build(key -> createExpensiveGraph(key));
 * }

and the JavaDoc comes out perfect

[graememorgan]

Urk. We have support for this, but it's being stripped from the OSS release, given it's pegged to Java 17, and @snippet is a Java 18 feature.

Apologies for the noise; Liam filed #4867 the other day to track bumping us to 21 externally as well as internally.

[ben-manes]

Oh I generate Javadoc using the later version than the source code. It works fine since the html rendering is independent and can target a release for the links, but maybe that is not strictly kosher.

[tbroyer]

Isn't just a case of adding snippet to PRE_TAGS in this case?

https://github.com/google/error-prone/blob/81faa5aed9cc3ddb38ff97d2ef497e44cd289c0d/core/src/main/java/com/google/errorprone/bugpatterns/javadoc/UnescapedEntity.java#L76

[graememorgan]

Isn't just a case of adding snippet to PRE_TAGS in this case?

@snippet is not an HTML tag.

Oh I generate Javadoc using the later version than the source code. It works fine since the html rendering is independent and can target a release for the links, but maybe that is not strictly kosher.

Sorry, what I meant is that the open source ErrorProne release only contains features up to 17, while @snippet is 18, so we don't yet have the "feature" of ignoring @snippet in the OSS release.

[tbroyer]

Isn't just a case of adding snippet to PRE_TAGS in this case?

@snippet is not an HTML tag.

silly me 🤦