Use Javadoc {@snippet ...} tag.

This CL is mostly just the output of an automated search-and-replace operation:
- `<pre>{@code$` -> `{@snippet :`
- `[*] }</pre>` -> `* }`

But I did touch up `ComparisonChain`, which had a workaround for using "`@Override`" at the beginning of a line of the code snippet. In the process, I discovered that we hadn't carried over the "Java 8" instructions to the backport. Now that we use library desugaring for all our internal builds, we should include these instructions in the backport, too. I've done so. External users may or may not be able to use these features yet.

I also touched up `Iterables` and `FluentIterable`, since the `Class` overload of their `filter` methods was using a different style so that it could contain a line that starts with "`@SuppressWarnings`."

This CL should be safe now that [the external Guava build uses newer versions of tools like `javadoc`](#6549), even as it continues to target (and test under) older JDKs.

The result of the CL is mostly that code snippets appear in a gray box with a copy button and slightly less whitespace.

RELNOTES=n/a
PiperOrigin-RevId: 737729648

Author: cpovirk

android/guava-testlib/src/com/google/common/collect/testing/IteratorTester.java

@@ -58,7 +58,7 @@
  * <p>For example, to test {@link java.util.Collections#unmodifiableList(java.util.List)
  * Collections.unmodifiableList}'s iterator:
  *
- * <pre>{@code
+ * {@snippet :
  * List<String> expectedElements =
  *     Arrays.asList("a", "b", "c", "d", "e");
  * List<String> actualElements =
@@ -77,7 +77,7 @@
  *     };
  * iteratorTester.test();
  * iteratorTester.testForEachRemaining();
- * }</pre>
+ * }
  *
  * <p><b>Note</b>: It is necessary to use {@code IteratorTester.KnownOrder} as shown above, rather
  * than {@code KnownOrder} directly, because otherwise the code cannot be compiled.

android/guava-testlib/src/com/google/common/testing/EquivalenceTester.java

@@ -36,12 +36,12 @@
  * contains objects that are supposed to be equal to each other. Objects of different groups are
  * expected to be unequal. For example:
  *
- * <pre>{@code
+ * {@snippet :
  * EquivalenceTester.of(someStringEquivalence)
  *     .addEquivalenceGroup("hello", "h" + "ello")
  *     .addEquivalenceGroup("world", "wor" + "ld")
  *     .test();
- * }</pre>
+ * }
  *
  * <p>Note that testing {@link Object#equals(Object)} is more simply done using the {@link
  * EqualsTester}. It includes an extra test against an instance of an arbitrary class without having

android/guava-testlib/src/com/google/common/testing/ForwardingWrapperTester.java

@@ -45,13 +45,13 @@
  *
  * <p>For example:
  *
- * <pre>{@code
+ * {@snippet :
  * new ForwardingWrapperTester().testForwarding(Foo.class, new Function<Foo, Foo>() {
  *   public Foo apply(Foo foo) {
  *     return new ForwardingFoo(foo);
  *   }
  * });
- * }</pre>
+ * }
  *
  * @author Ben Yu
  * @since 14.0

android/guava-testlib/src/com/google/common/testing/GcFinalization.java

@@ -56,32 +56,32 @@
  *
  * <p>Here's an example that tests a {@code finalize} method:
  *
- * <pre>{@code
+ * {@snippet :
  * final CountDownLatch latch = new CountDownLatch(1);
  * Object x = new MyClass() {
  *   ...
  *   protected void finalize() { latch.countDown(); ... }
  * };
  * x = null;  // Hint to the JIT that x is stack-unreachable
  * GcFinalization.await(latch);
- * }</pre>
+ * }
  *
  * <p>Here's an example that uses a user-defined finalization predicate:
  *
- * <pre>{@code
+ * {@snippet :
  * final WeakHashMap<Object, Object> map = new WeakHashMap<>();
  * map.put(new Object(), Boolean.TRUE);
  * GcFinalization.awaitDone(new FinalizationPredicate() {
  *   public boolean isDone() {
  *     return map.isEmpty();
  *   }
  * });
- * }</pre>
+ * }
  *
  * <p>Even if your non-test code does not use finalization, you can use this class to test for
  * leaks, by ensuring that objects are no longer strongly referenced:
  *
- * <pre>{@code
+ * {@snippet :
  * // Helper function keeps victim stack-unreachable.
  * private WeakReference<Foo> fooWeakRef() {
  *   Foo x = ....;
@@ -93,7 +93,7 @@
  * public void testFooLeak() {
  *   GcFinalization.awaitClear(fooWeakRef());
  * }
- * }</pre>
+ * }
  *
  * <p>This class cannot currently be used to test soft references, since this class does not try to
  * create the memory pressure required to cause soft references to be cleared.
@@ -261,13 +261,13 @@ public interface FinalizationPredicate {
    *
    * <p>This is a convenience method, equivalent to:
    *
-   * <pre>{@code
+   * {@snippet :
    * awaitDone(new FinalizationPredicate() {
    *   public boolean isDone() {
    *     return ref.get() == null;
    *   }
    * });
-   * }</pre>
+   * }
    *
    * @throws RuntimeException if timed out or interrupted while waiting
    */

android/guava-tests/test/com/google/common/graph/TraverserTest.java

@@ -42,40 +42,40 @@ public class TraverserTest {
   /**
    * The undirected graph in the {@link Traverser#breadthFirst(Object)} javadoc:
    *
-   * <pre>{@code
+   * {@snippet :
    * b ---- a ---- d
    * |      |
    * |      |
    * e ---- c ---- f
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> JAVADOC_GRAPH =
       createUndirectedGraph("ba", "ad", "be", "ac", "ec", "cf");
 
   /**
    * A diamond shaped directed graph (arrows going down):
    *
-   * <pre>{@code
+   * {@snippet :
    *   a
    *  / \
    * b   c
    *  \ /
    *   d
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> DIAMOND_GRAPH =
       createDirectedGraph("ab", "ac", "bd", "cd");
 
   /**
    * Same as {@link #DIAMOND_GRAPH}, but with an extra c->a edge and some self edges:
    *
-   * <pre>{@code
+   * {@snippet :
    *   a<>
    *  / \\
    * b   c
    *  \ /
    *   d<>
-   * }</pre>
+   * }
    *
    * {@code <>} indicates a self-loop
    */
@@ -89,21 +89,21 @@ public class TraverserTest {
   /**
    * Same as {@link #CYCLE_GRAPH}, but with an extra a->c edge.
    *
-   * <pre>{@code
+   * {@snippet :
    * |--------------|
    * v              |
    * a -> b -> c -> d
    * |         ^
    * |---------|
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> TWO_CYCLES_GRAPH =
       createDirectedGraph("ab", "ac", "bc", "cd", "da");
 
   /**
    * A tree-shaped graph that looks as follows (all edges are directed facing downwards):
    *
-   * <pre>{@code
+   * {@snippet :
    *        h
    *       /|\
    *      / | \
@@ -112,29 +112,29 @@ public class TraverserTest {
    *   /|\      |
    *  / | \     |
    * a  b  c    f
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> TREE =
       createDirectedGraph("hd", "he", "hg", "da", "db", "dc", "gf");
 
   /**
    * Two disjoint tree-shaped graphs that look as follows (all edges are directed facing downwards):
    *
-   * <pre>{@code
+   * {@snippet :
    * a   c
    * |   |
    * |   |
    * b   d
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> TWO_TREES = createDirectedGraph("ab", "cd");
 
   /**
    * A graph consisting of a single root {@code a}:
    *
-   * <pre>{@code
+   * {@snippet :
    * a
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> SINGLE_ROOT = createSingleRootGraph();
 
@@ -143,13 +143,13 @@ public class TraverserTest {
    * {@code f} and thus has a cycle) but is a valid input to {@link Traverser#forTree} when starting
    * e.g. at node {@code a} (all edges without an arrow are directed facing downwards):
    *
-   * <pre>{@code
+   * {@snippet :
    *     a
    *    /
    *   b   e <----> f
    *  / \ /
    * c   d
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> CYCLIC_GRAPH_CONTAINING_TREE =
       createDirectedGraph("ab", "bc", "bd", "ed", "ef", "fe");
@@ -159,13 +159,13 @@ public class TraverserTest {
    * e} and {@code g}) but is a valid input to {@link Traverser#forTree} when starting e.g. at node
    * {@code a} (all edges are directed facing downwards):
    *
-   * <pre>{@code
+   * {@snippet :
    *     a   f
    *    /   / \
    *   b   e   g
    *  / \ / \ /
    * c   d   h
-   * }</pre>
+   * }
    */
   private static final SuccessorsFunction<Character> GRAPH_CONTAINING_TREE_AND_DIAMOND =
       createDirectedGraph("ab", "fe", "fg", "bc", "bd", "ed", "eh", "gh");

android/guava-tests/test/com/google/common/reflect/SubtypeTester.java

@@ -42,7 +42,7 @@
  * <p>These declaration methods rely on Java static type checking to make sure what we want to
  * assert as subtypes are really subtypes according to javac. For example:
  *
- * <pre>{@code
+ * {@snippet :
  * class MySubtypeTests extends SubtypeTester {
  *   @TestSubtype(suppressGetSubtype = true, suppressGetSupertype = true)
  *   public <T> Iterable<? extends T> listIsSubtypeOfIterable(List<T> list) {
@@ -58,7 +58,7 @@
  * public void testMySubtypes() throws Exception {
  *   new MySubtypeTests().testAllDeclarations();
  * }
- * }</pre>
+ * }
  *
  * The calls to {@link #isSubtype} and {@link #notSubtype} tells the framework what assertions need
  * to be made.

android/guava/src/com/google/common/base/Ascii.java

@@ -523,10 +523,10 @@ public static boolean isUpperCase(char c) {
    *
    * <p>Examples:
    *
-   * <pre>{@code
+   * {@snippet :
    * Ascii.truncate("foobar", 7, "..."); // returns "foobar"
    * Ascii.truncate("foobar", 5, "..."); // returns "fo..."
-   * }</pre>
+   * }
    *
    * <p><b>Note:</b> This method <i>may</i> work with certain non-ASCII text but is not safe for use
    * with arbitrary Unicode text. It is mostly intended for use with text that is known to be safe

android/guava/src/com/google/common/base/CharMatcher.java

@@ -609,9 +609,9 @@ public int countIn(CharSequence sequence) {
    * Returns a string containing all non-matching characters of a character sequence, in order. For
    * example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.is('a').removeFrom("bazaar")
-   * }</pre>
+   * }
    *
    * ... returns {@code "bzr"}.
    */
@@ -648,9 +648,9 @@ public String removeFrom(CharSequence sequence) {
    * Returns a string containing all matching BMP characters of a character sequence, in order. For
    * example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.is('a').retainFrom("bazaar")
-   * }</pre>
+   * }
    *
    * ... returns {@code "aaa"}.
    */
@@ -662,9 +662,9 @@ public String retainFrom(CharSequence sequence) {
    * Returns a string copy of the input character sequence, with each matching BMP character
    * replaced by a given replacement character. For example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.is('a').replaceFrom("radar", 'o')
-   * }</pre>
+   * }
    *
    * ... returns {@code "rodor"}.
    *
@@ -697,9 +697,9 @@ public String replaceFrom(CharSequence sequence, char replacement) {
    * Returns a string copy of the input character sequence, with each matching BMP character
    * replaced by a given replacement sequence. For example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.is('a').replaceFrom("yaha", "oo")
-   * }</pre>
+   * }
    *
    * ... returns {@code "yoohoo"}.
    *
@@ -745,17 +745,17 @@ public String replaceFrom(CharSequence sequence, CharSequence replacement) {
    * Returns a substring of the input character sequence that omits all matching BMP characters from
    * the beginning and from the end of the string. For example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.anyOf("ab").trimFrom("abacatbab")
-   * }</pre>
+   * }
    *
    * ... returns {@code "cat"}.
    *
    * <p>Note that:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.inRange('\0', ' ').trimFrom(str)
-   * }</pre>
+   * }
    *
    * ... is equivalent to {@link String#trim()}.
    */
@@ -782,9 +782,9 @@ public String trimFrom(CharSequence sequence) {
    * Returns a substring of the input character sequence that omits all matching BMP characters from
    * the beginning of the string. For example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.anyOf("ab").trimLeadingFrom("abacatbab")
-   * }</pre>
+   * }
    *
    * ... returns {@code "catbab"}.
    */
@@ -802,9 +802,9 @@ public String trimLeadingFrom(CharSequence sequence) {
    * Returns a substring of the input character sequence that omits all matching BMP characters from
    * the end of the string. For example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.anyOf("ab").trimTrailingFrom("abacatbab")
-   * }</pre>
+   * }
    *
    * ... returns {@code "abacat"}.
    */
@@ -822,9 +822,9 @@ public String trimTrailingFrom(CharSequence sequence) {
    * Returns a string copy of the input character sequence, with each group of consecutive matching
    * BMP characters replaced by a single replacement character. For example:
    *
-   * <pre>{@code
+   * {@snippet :
    * CharMatcher.anyOf("eko").collapseFrom("bookkeeper", '-')
-   * }</pre>
+   * }
    *
    * ... returns {@code "b-p-r"}.
    *