Extensive documentation of TraversableLike in p...

Extensive documentation of TraversableLike in proposed new style.

1 files changed, 34 insertions, 10 deletions

diff --git a/src/library/scala/collection/Traversable.scala b/src/library/scala/collection/Traversable.scala
index 2cf66e80a2..abc9c74ed6 100644
--- a/src/library/scala/collection/Traversable.scala
+++ b/src/library/scala/collection/Traversable.scala
@@ -15,20 +15,44 @@ import generic._
 import mutable.{Builder, Buffer, ArrayBuffer, ListBuffer}
 import scala.util.control.Breaks
 
-/** <p>
- *    A template trait for traversable collections.
- *  </p>
- *  <p>
- *    Collection classes mixing in this trait provide a method
- *    <code>foreach</code> which traverses all the
- *    elements contained in the collection, applying a given procedure to each.
- *    They also provide a method <code>newBuilder</code>
- *    which creates a builder for collections of the same kind.
- *  </p>
+/** A template trait for traversable collections.
+ *
+ *  Collection classes mixing in this trait provide a method
+ *  `foreach` which traverses all the elements contained in the collection, applying
+ *  a given procedure to each element.
+ *  They also provide a method <code>newBuilder</code>
+ *  which creates a builder for collections of the same kind.
+ *
+ *  A traversable class might or might not have two properties: strictness
+ *  and orderedness. Neither is represented as a type.
+ *
+ *  The instances of a strict collection class have all their elements
+ *  computed before they can be used as values. By contrast, instances of
+ *  a non-strict collection class may defer computation of some of their
+ *  elements until after the instance is available as a value.
+ *  A typical example of a non-strict collection class is a
+ *  <a href="../immutable/Stream.html" target="ContentFrame">
+ *  `scala.collection.immutable.Stream`</a>.
+ *  A more general class of examples are `TraversableViews`.
+ *
+ *  If a collection is an instance of an ordered collection class, traversing
+ *  its elements with `foreach` will always visit elements in the
+ *  same order, even for different runs of the program. If the class is not
+ *  ordered, `foreach` can visit elements in different orders for
+ *  different runs (but it will keep the same order in the same run).'
+ *
+ *  A typical example of a collection class which is not ordered is a
+ *  `HashMap` of objects. The traversal order for hash maps will
+ *  depend on the hash codes of its elements, and these hash codes might
+ *  differ from one run to the next. By contrast, a `LinkedHashMap`
+ *  is ordered because it's `foreach` method visits elements in the
+ *  order they were inserted into the `HashMap`.
  *
  *  @author Martin Odersky
  *  @version 2.8
  *  @since   2.8
+ *
+ *  @tparam A    The element type of the collection
  */
 trait Traversable[+A] extends TraversableLike[A, Traversable[A]]
                          with GenericTraversableTemplate[A, Traversable] {