* additional documentation, including:
 *
 * <ul>
 *   <li><a
 *       href="https://github.com/google/guava/wiki/GraphsExplained#equals-hashcode-and-graph-equivalence">
 *       {@code equals()}, {@code hashCode()}, and graph equivalence</a>
 *   <li><a href="https://github.com/google/guava/wiki/GraphsExplained#synchronization">
 *       Synchronization policy</a>

 * by supplied comparators. In all cases, this implementation uses {@link Comparable#compareTo} or
 * {@link Comparator#compare} instead of {@link Object#equals} to determine equivalence of
 * instances.
 *
 * <p><b>Warning:</b> The comparators or comparables used must be <i>consistent with equals</i> as
 * explained by the {@link Comparable} class specification. Otherwise, the resulting multiset will

    Map<Integer, String> right = ImmutableMap.of(1, "A", 3, "F", 5, "G", 6, "Z");

    // TODO(kevinb): replace with Ascii.caseInsensitiveEquivalence() when it
    // exists
    Equivalence<String> caseInsensitiveEquivalence =
        Equivalence.equals()
            .onResultOf(
                new Function<String, String>() {
                  @Override
                  public String apply(String input) {

   * @param valueEquivalence the equivalence relationship to use to compare values
   * @return the difference between the two maps
   * @since 10.0
   */
  public static <K extends @Nullable Object, V extends @Nullable Object>
      MapDifference<K, V> difference(
          Map<? extends K, ? extends V> left,
          Map<? extends K, ? extends V> right,
          Equivalence<? super @NonNull V> valueEquivalence) {

   * @param valueEquivalence the equivalence relationship to use to compare values
   * @return the difference between the two maps
   * @since 10.0
   */
  public static <K extends @Nullable Object, V extends @Nullable Object>
      MapDifference<K, V> difference(
          Map<? extends K, ? extends V> left,
          Map<? extends K, ? extends V> right,
          Equivalence<? super @NonNull V> valueEquivalence) {

    Map<Integer, String> right = ImmutableMap.of(1, "A", 3, "F", 5, "G", 6, "Z");

    // TODO(kevinb): replace with Ascii.caseInsensitiveEquivalence() when it
    // exists
    Equivalence<String> caseInsensitiveEquivalence =
        Equivalence.equals()
            .onResultOf(
                new Function<String, String>() {
                  @Override
                  public String apply(String input) {

   * given object is also a multiset and contains equal elements with equal counts, regardless of
   * order.
   */
  @Override
  // TODO(kevinb): caveats about equivalence-relation?
  boolean equals(@Nullable Object object);

  /**
   * Returns the hash code for this multiset. This is defined as the sum of
   *
   * {@snippet :

   * given object is also a multiset and contains equal elements with equal counts, regardless of
   * order.
   */
  @Override
  // TODO(kevinb): caveats about equivalence-relation?
  boolean equals(@Nullable Object object);

  /**
   * Returns the hash code for this multiset. This is defined as the sum of
   *
   * {@snippet :

 * or an explicit {@link Comparator}. In all cases, this implementation uses {@link
 * Comparable#compareTo} or {@link Comparator#compare} instead of {@link Object#equals} to determine
 * equivalence of instances.
 *
 * <p><b>Warning:</b> The comparison must be <i>consistent with equals</i> as explained by the
 * {@link Comparable} class specification. Otherwise, the resulting multiset will violate the {@link

 * or an explicit {@link Comparator}. In all cases, this implementation uses {@link
 * Comparable#compareTo} or {@link Comparator#compare} instead of {@link Object#equals} to determine
 * equivalence of instances.
 *
 * <p><b>Warning:</b> The comparison must be <i>consistent with equals</i> as explained by the
 * {@link Comparable} class specification. Otherwise, the resulting multiset will violate the {@link