*
     * Unfortunately, we don't distinguish between these two cases in our public API: Joiner.on(...)
     * and Joiner.on(...).useForNull(...) both declare the same return type: plain Joiner. To ensure
     * that users *can* pass null arguments to Joiner, we annotate it as if it always tolerates null
     * inputs, rather than as if it never tolerates them.
     *

    }
  }

  /**
   * Returns a {@link Collection} of all the permutations of the specified {@link Collection}.
   *
   * <p><i>Notes:</i> This is an implementation of the Plain Changes algorithm for permutations
   * generation, described in Knuth's "The Art of Computer Programming", Volume 4, Chapter 7,
   * Section 7.2.1.2.
   *

      return this;
    }

    private void add(@Nullable Object[] elements, int n) {
      getReadyToExpandTo(size + n);
      /*
       * The following call is not statically checked, since arraycopy accepts plain Object for its
       * parameters. If it were statically checked, the checker would still be OK with it, since
       * we're copying into a `contents` array whose type allows it to contain nulls. Still, it's

 * Benchmarks (as of December 2011) show that:
 *
 * <ul>
 *   <li>for an unnested {@code lock()} and {@code unlock()}, a cycle detecting lock takes 38ns as
 *       opposed to the 24ns taken by a plain lock.
 *   <li>for nested locking, the cost increases with the depth of the nesting:
 *       <ul>
 *         <li>2 levels: average of 64ns per lock()/unlock()
 *         <li>3 levels: average of 77ns per lock()/unlock()

   * returns. This method may be useful when testing the garbage collection mechanism itself, or
   * inhibiting a spontaneous GC initiation in subsequent code.
   *
   * <p>In contrast, a plain call to {@link java.lang.System#gc()} does not ensure finalization
   * processing and may run concurrently, for example, if the JVM flag {@code
   * -XX:+ExplicitGCInvokesConcurrent} is used.
   *

       *
       * (And I don't believe there's any situation in which we call x.combine(y) when x is a plain
       * ImmutableSet.Builder but y is an ImmutableSortedSet.Builder (or vice versa). Certainly
       * ImmutableSortedSet.Builder.combine() is written as if its argument will never be a plain
       * ImmutableSet.Builder: It casts immediately to ImmutableSortedSet.Builder.)
       */
      copyIfNecessary();

 *       considered "compiled comments."
 *   <li>An explicit {@code if/throw} (as illustrated below) is always acceptable; we still
 *       recommend using our {@link VerifyException} exception type. Throwing a plain {@link
 *       RuntimeException} is frowned upon.
 *   <li>Use of {@link java.util.Objects#requireNonNull(Object)} is generally discouraged, since

     *
     * 1. We'll want to use something like @PolyNull once we can make that work for the various
     * platforms we target.
     *
     * 2. Kotlin's Map type has a getOrDefault method that accepts and returns a "plain V," in
     * contrast to the "V?" type that we're using. As a result, Kotlin sees a conflict between the
     * nullness annotations in ImmutableMap and those in its own Map type. In response, it considers

    }
  }

  /**
   * Returns a {@link Collection} of all the permutations of the specified {@link Collection}.
   *
   * <p><i>Notes:</i> This is an implementation of the Plain Changes algorithm for permutations
   * generation, described in Knuth's "The Art of Computer Programming", Volume 4, Chapter 7,
   * Section 7.2.1.2.
   *

   * returns. This method may be useful when testing the garbage collection mechanism itself, or
   * inhibiting a spontaneous GC initiation in subsequent code.
   *
   * <p>In contrast, a plain call to {@link java.lang.System#gc()} does not ensure finalization
   * processing and may run concurrently, for example, if the JVM flag {@code
   * -XX:+ExplicitGCInvokesConcurrent} is used.
   *