lost of documentation and some small adjustment...

lost of documentation and some small adjustments to collection classes.

1 files changed, 29 insertions, 34 deletions

diff --git a/src/library/scala/collection/IterableLike.scala b/src/library/scala/collection/IterableLike.scala
index 41dc774cd9..06db5fb6fc 100644
--- a/src/library/scala/collection/IterableLike.scala
+++ b/src/library/scala/collection/IterableLike.scala
@@ -13,40 +13,38 @@ import generic._
 import immutable.{List, Stream}
 import annotation.unchecked.uncheckedVariance
 
-/** <p>
- *    A template trait for iterable collections of type `Iterable[A]`.
- *  </p>
- *  <p>
- *    Collection classes mixing in this trait provide a method
- *    <code>iterator</code> which returns an iterator over all the
- *    elements contained in the collection. They also provide a method
- *    <code>newBuilder</code> which creates a builder for collections of the
- *    same kind.
- *  </p>
- *  <p>
- *    This trait implements <code>Iterable</code>'s <code>foreach</code>
- *    method by stepping through all elements. Subclasses of <code>Iterable</code>
- *    should re-implement <code>foreach</code> with something more efficient,
- *    if possible.
- *  </p>
- *  <p>
- *    This trait adds methods <code>iterator</code>, <code>sameElements</code>,
- *    <code>takeRight</code>, <code>dropRight</code> to the methods inherited
- *    from trait <a href="../Iterable.html" target="ContentFrame">
- *    <code>Iterable</code></a>.
- *  </p>
- *
- *  Note: This trait replaces every method that uses breaks in the original by an iterator version.
+/** A template trait for iterable collections of type `Iterable[A]`.
+ *  $iterableInfo
+ *  @tparam A    the element type of the collection
+ *  @tparam Repr the type of the actual collection containing the elements.
+ *  @define iterableInfo
+ *    This is a base trait for all scala collections that define an `iterator`
+ *    method to step through one-by-one the collection's elements.
+ *    Implementations of this trait need to provide a concrete method with
+ *    signature:
+ *    {{{
+ *       def iterator: Iterator[A]
+ *    }}}
+ *    They also need to provide a method `newBuilder`
+ *    which creates a builder for collections of the same kind.
  *
- *  @see Iterable
+ *    This trait implements `Iterable`'s `foreach`
+ *    method by stepping through all elements using `iterator`.
+ *    Subclasses should re-implement `foreach` with something more efficient,
+ *    if possible.
+
+ *    This trait adds methods `iterator`, `sameElements`,
+ *    `takeRight`, `dropRight` to the methods inherited
+ *    from trait <a href="../Traversable.html" target="ContentFrame">
+ *    `Traversable`</a>.
+
+ *    Note: This trait replaces every method that uses `break` in
+ *    `TraversableLike` by an iterator version.
  *
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
  *
- *  @tparam A    the element type of the collection
- *  @tparam Repr the type of the actual collection containing the elements.
- *
  *  @define Coll Iterable
  *  @define coll iterable collection
  *  @define zipthatinfo the class of the returned collection. Where possible, `That` is
@@ -337,19 +335,16 @@ self =>
 
   override /*TraversableLike*/ def view(from: Int, until: Int) = view.slice(from, until)
 
-  /** @deprecated use `head' instead. */
   @deprecated("use `head' instead") def first: A = head
 
-  /** <code>None</code> if iterable is empty.
-   *  @deprecated "use `headOption' instead"
+  /** `None` if iterable is empty.
    */
   @deprecated("use `headOption' instead") def firstOption: Option[A] = headOption
 
   /**
-   * returns a projection that can be used to call non-strict <code>filter</code>,
-   * <code>map</code>, and <code>flatMap</code> methods that build projections
+   * returns a projection that can be used to call non-strict `filter`,
+   * `map`, and `flatMap` methods that build projections
    * of the collection.
-   * @deprecated "use `view' instead"
    */
   @deprecated("use `view' instead")
   def projection = view