*
   * <p>For example,
   *
   * {@snippet :
   * List<String> badGuys = Arrays.asList("Inky", "Blinky", "Pinky", "Pinky", "Clyde");
   * Function<String, Integer> stringLengthFunction = ...;
   * Multimap<Integer, String> index = Multimaps.index(badGuys, stringLengthFunction);
   * System.out.println(index);
   * }
   *
   * <p>prints
   *
   * {@snippet :
   * {4=[Inky], 6=[Blinky], 5=[Pinky, Pinky, Clyde]}

 * except that they are always enabled. These methods should be used instead of Java assertions
 * whenever there is a chance the check may fail "in real life". Example:
 *
 * {@snippet :
 * Bill bill = remoteService.getLastUnpaidBill();
 *
 * // In case bug 12345 happens again we'd rather just die
 * Verify.verify(bill.status() == Status.UNPAID,
 *     "Unexpected bill status: %s", bill.status());
 * }

   * lists in order; the "n-ary <a href="http://en.wikipedia.org/wiki/Cartesian_product">Cartesian
   * product</a>" of the lists. For example:
   *
   * {@snippet :
   * Lists.cartesianProduct(ImmutableList.of(
   *     ImmutableList.of(1, 2),
   *     ImmutableList.of("A", "B", "C")))
   * }
   *
   * <p>returns a list containing six lists in the following order:
   *

 * its {@code close} method. You could use a finalizer to accomplish this, but that has a
 * number of well-known problems. Here is how you might use this class instead:
 *
 * {@snippet :
 * public class MyServer implements Closeable {
 *   private static final FinalizableReferenceQueue frq = new FinalizableReferenceQueue();
 *   // You might also share this between several objects.
 *

   * Maps#asMap(Set, Function)}.
   *
   * <p><b>Note:</b> on Java 8+, it is usually better to use streams. For example:
   *
   * {@snippet :
   * import static com.google.common.collect.ImmutableMap.toImmutableMap;
   * ...
   * ImmutableMap<Color, String> colorNames =
   *     allColors.stream().collect(toImmutableMap(c -> c, c -> c.toString()));

   * Maps#asMap(Set, Function)}.
   *
   * <p><b>Note:</b> on Java 8+, it is usually better to use streams. For example:
   *
   * {@snippet :
   * import static com.google.common.collect.ImmutableMap.toImmutableMap;
   * ...
   * ImmutableMap<Color, String> colorNames =
   *     allColors.stream().collect(toImmutableMap(c -> c, c -> c.toString()));

 * to be closed asynchronously <b>after</b> the returned {@code Future} is done: the future
 * completes before closing starts, rather than once it has finished.
 *
 * {@snippet :
 * FluentFuture<UserName> userName =
 *     ClosingFuture.submit(
 *             closer -> closer.eventuallyClose(database.newTransaction(), closingExecutor),
 *             executor)

 * {@link Map}) with a separator. It either appends the results to an {@link Appendable} or returns
 * them as a {@link String}. Example:
 *
 * {@snippet :
 * Joiner joiner = Joiner.on("; ").skipNulls();
 *  . . .
 * return joiner.join("Harry", null, "Ron", "Hermione");
 * }
 *
 * <p>This returns the string {@code "Harry; Ron; Hermione"}. Note that all input elements are

   * through the returned queue.
   *
   * <p>It is imperative that the user manually synchronize on the returned queue when accessing the
   * queue's iterator:
   *
   * {@snippet :
   * Queue<E> queue = Queues.synchronizedQueue(MinMaxPriorityQueue.<E>create());
   * ...
   * queue.add(element); // Needn't be in synchronized block
   * ...
   * synchronized (queue) { // Must synchronize on queue!

 * except that they are always enabled. These methods should be used instead of Java assertions
 * whenever there is a chance the check may fail "in real life". Example:
 *
 * {@snippet :
 * Bill bill = remoteService.getLastUnpaidBill();
 *
 * // In case bug 12345 happens again we'd rather just die
 * Verify.verify(bill.status() == Status.UNPAID,
 *     "Unexpected bill status: %s", bill.status());
 * }