Rewrite javadocs for immutable collections.

-------------
Created by MOE: http://code.google.com/p/moe-java
MOE_MIGRATED_REVID=86995462

guava/src/com/google/common/collect/ImmutableCollection.java

@@ -24,26 +24,145 @@
 
 import java.io.Serializable;
 import java.util.AbstractCollection;
+import java.util.ArrayList;
 import java.util.Collection;
+import java.util.Collections;
 import java.util.Iterator;
+import java.util.List;
 
 import javax.annotation.Nullable;
 
 /**
- * An immutable collection. Does not permit null elements.
+ * A subtype of {@link Collection} making additional guarantees: its contents will never change, it
+ * will never contain {@code null}, and its iteration order is deterministic.
  *
- * <p>In addition to the {@link Collection} methods, this class has an {@link
- * #asList()} method, which returns a list view of the collection's elements.
+ * <p><b>Note:</b> {@code ImmutableCollection} itself exists primarily as a common supertype for
+ * more useful types like {@link ImmutableSet} and {@link ImmutableList}. Like {@code Collection},
+ * it has no defined {@link #equals} behavior, which can lead to surprises and bugs, so (like {@code
+ * Collection}) it should not be used directly.
  *
- * <p><b>Note:</b> Although this class is not final, it cannot be subclassed
- * outside of this package as it has no public or protected constructors. Thus,
- * instances of this type are guaranteed to be immutable.
+ * <p>Example usage: <pre>   {@code
+ *
+ *   class Foo {
+ *     private static final ImmutableSet<String> RESERVED_CODES =
+ *         ImmutableSet.of("AZ", "CQ", "ZX");
+ *
+ *     private final ImmutableSet<String> codes;
+ *
+ *     public Foo(Iterable<String> codes) {
+ *       this.codes = ImmutableSet.copyOf(codes);
+ *       checkArgument(Collections.disjoint(this.codes, RESERVED_CODES));
+ *   }
+ *
+ * <h3>About <i>all</i> public {@code Immutable-} types in this package</h3>
+ *
+ * <h4>Guarantees</h4>
+ *
+ * <p>Each makes the following guarantees:
+ *
+ * <ul>
+ * <li>Its contents can never change. Any attempt to add, remove or replace an element results in an
+ *     {@link UnsupportedOperationException}. Note that this guarantee of <i>immutability</i> is
+ *     stronger than that of {@link Collections#unmodifiableCollection}, which only prevents
+ *     modification operations from being invoked on the reference it returns, while any other code
+ *     having a reference to the inner collection can still modify it at will.
+ * <li>It can never contain {@code null} as an element, key or value. An attempt to do so results in
+ *     a {@link NullPointerException}.
+ * <li>Its iteration order is deterministic. What that order is, specifically, depends on how the
+ *     collection was created. See the appropriate factory method for details.
+ * <li>It cannot be subclassed outside this package (which would permit these guarantees to be
+ *     violated).
+ * <li>It is thread-safe.
+ * </ul>
+ *
+ * <h4>Types, not implementations</h4>
+ *
+ * <p>Each of these public classes, such as {@code ImmutableList}, is a <i>type</i>, not a
+ * specific <i>implementation</i> (unlike the case of, say, {@link ArrayList}). That is, they should
+ * be thought of as interfaces in virtually every important sense, just ones that classes outside
+ * this package can't implement.
+ *
+ * <p>For your field types and method return types, use the immutable type (like {@code
+ * ImmutableList}) instead of the corresponding basic collection interface type (like {@link List})
+ * unless the semantic guarantees listed above are not considered relevant. On the other hand, a
+ * <i>parameter</i> type of {@code ImmutableList} can be a nuisance to callers; instead, accept
+ * {@link List} (or even {@link Iterable}) and pass it to {@link ImmutableList#copyOf(Collection)}
+ * yourself.
+ *
+ * <h4>Creation</h4>
+ *
+ * <p>With the exception of {@code ImmutableCollection} itself, each {@code Immutable} type provides
+ * the static operations you need to obtain instances of that type:
+ *
+ * <ul>
+ * <li>Static methods named {@code of} accepting an explicit list of elements or entries
+ * <li>Static methods named {@code copyOf} accepting an existing collection (or similar) whose
+ *     contents should be copied
+ * <li>A static nested {@code Builder} class which can be used to progressively populate a new
+ *     immutable instance
+ * </ul>
+ *
+ * <h4>Other common properties</h4>
+ *
+ * <ul>
+ * <li>View collections, such as {@link ImmutableMap#keySet} or {@link ImmutableList#subList},
+ *     return the appropriate {@code Immutable} type. This is true even when the language does not
+ *     permit the method's return type to express it (for example in the case of {@link
+ *     ImmutableListMultimap#asMap}).
+ *
+ * <h4>Performance notes</h4>
+ *
+ * <ul>
+ * <li>When a {@code copyOf} method is passed a collection that is already immutable, in most cases
+ *     it can return quickly without actually copying anything. This means that making defensive
+ *     copies at API boundaries as a habit is not necessarily expensive in the long run.
+ * <li>Implementations can be generally assumed to prioritize memory efficiency and speed of access
+ *     over speed of creation.
+ * <li>The performance of using the associated {@code Builder} class can generally be assumed to be
+ *     no worse, and possibly better, than creating a mutable collection and copying it.
+ * <li>Implementations generally do not cache hash codes. If your key type has a slow {@code
+ *     hashCode} implementation, it should cache it itself.
+ * </ul>
+ *
+ * <h4>Notable subtypes (not exhaustive)</h4>
+ *
+ * <ul>
+ * <li>{@code ImmutableCollection}
+ *     <ul>
+ *     <li>{@link ImmutableSet}
+ *         <ul>
+ *         <li>{@link ImmutableSortedSet}
+ *         </ul>
+ *     <li>{@link ImmutableList}
+ *     <li>{@link ImmutableMultiset}
+ *     </ul>
+ * <li>{@link ImmutableMap}
+ *     <ul>
+ *     <li>{@link ImmutableSortedMap}
+ *     <li>{@link ImmutableBiMap}
+ *     </ul>
+ * <li>{@link ImmutableMultimap}
+ *     <ul>
+ *     <li>{@link ImmutableListMultimap}
+ *     <li>{@link ImmutableSetMultimap}
+ *     </ul>
+ * <li>{@link ImmutableTable}
+ * <li>{@link ImmutableRangeSet}
+ * <li>{@link ImmutableRangeMap}
+ * </ul>
+ *
+ * <h3>See also</h3>
+ *
+ * <p>See the Guava User Guide article on <a href=
+ * "http://code.google.com/p/guava-libraries/wiki/ImmutableCollectionsExplained">
+ * immutable collections</a>.
  *
- * @author Jesse Wilson
  * @since 2.0 (imported from Google Collections Library)
  */
 @GwtCompatible(emulated = true)
 @SuppressWarnings("serial") // we're overriding default serialization
+// TODO(kevinb): I think we should push everything down to "BaseImmutableCollection" or something,
+// just to do everything we can to emphasize the "practically an interface" nature of this class.
 public abstract class ImmutableCollection<E> extends AbstractCollection<E>
     implements Serializable {
 
@@ -161,7 +280,12 @@ public final void clear() {
   private transient ImmutableList<E> asList;
 
   /**
-   * Returns a list view of the collection.
+   * Returns an {@code ImmutableList} containing the same elements, in the same order, as this
+   * collection.
+   *
+   * <p><b>Performance note:</b> in most cases this method can return quickly without actually
+   * copying anything. The exact circumstances under which the copy is performed are undefined and
+   * subject to change.
    *
    * @since 2.0
    */