- Update Scaladoc for LinkedList and for some o...

- Update Scaladoc for LinkedList and for some of the functions/operators
- that it inherits. Completed Scaladoc for append Added example
- in GenSeqLike for apply. Added $collectExample to collect in
- GenTraversableLike and supplied an actual example in LinkedList

Contributed by Donald McLean.

7 files changed, 311 insertions, 40 deletions

diff --git a/src/library/scala/collection/GenSeqLike.scala b/src/library/scala/collection/GenSeqLike.scala
index 56034273f0..57e5105e23 100644
--- a/src/library/scala/collection/GenSeqLike.scala
+++ b/src/library/scala/collection/GenSeqLike.scala
@@ -34,6 +34,16 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa
 
   /** Selects an element by its index in the $coll.
    *
+   * Example:
+   *
+   * {{{
+   *    scala> val x = LinkedList(1, 2, 3, 4, 5)
+   *    x: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4, 5)
+   *
+   *    scala> x(3)
+   *    res1: Int = 4
+   * }}}
+   *
    *  @param  idx  The index to select.
    *  @return the element of this $coll at index `idx`, where `0` indicates the first element.
    *  @throws `IndexOutOfBoundsException` if `idx` does not satisfy `0 <= idx < length`.
@@ -263,6 +273,22 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa
   def updated[B >: A, That](index: Int, elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** A copy of the $coll with an element prepended.
+   *
+   * Note that :-ending operators are right associative (see example).
+   * Also, the original $coll is not modified, so you will want to capture the result.
+   *
+   *  Example:
+   *  {{{
+   *      scala> val x = LinkedList(1)
+   *      x: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
+   *
+   *      scala> val y = 2 +: x
+   *      y: scala.collection.mutable.LinkedList[Int] = LinkedList(2, 1)
+   *
+   *      scala> println(x)
+   *      LinkedList(1)
+   *  }}}
+   *
    *  @param  elem   the prepended element
    *  @tparam B      the element type of the returned $coll.
    *  @tparam That   $thatinfo
@@ -276,6 +302,7 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa
   def +:[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** A copy of this $coll with an element appended.
+   *
    *  $willNotTerminateInf
    *  @param  elem   the appended element
    *  @tparam B      the element type of the returned $coll.
@@ -286,10 +313,25 @@ trait GenSeqLike[+A, +Repr] extends GenIterableLike[A, Repr] with Equals with Pa
    *  @usecase def :+(elem: A): $Coll[A]
    *  @return a new $coll consisting of
    *          all elements of this $coll followed by `elem`.
+   *  @example
+   *  {{{
+   *       scala> import scala.collection.mutable.LinkedList
+   *       import scala.collection.mutable.LinkedList
+   *
+   *       scala> val a = LinkedList(1)
+   *       a: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
+   *
+   *       scala> val b = a :+ 2
+   *       b: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *
+   *       scala> println(a)
+   *       LinkedList(1)
+   *  }}}
    */
   def :+[B >: A, That](elem: B)(implicit bf: CanBuildFrom[Repr, B, That]): That
 
   /** A copy of this $coll with an element value appended until a given target length is reached.
+   *
    *  @param   len   the target length
    *  @param   elem  the padding value
    *  @tparam B      the element type of the returned $coll.
diff --git a/src/library/scala/collection/GenTraversableLike.scala b/src/library/scala/collection/GenTraversableLike.scala
index fbb8b96ba4..dc89bcf85d 100644
--- a/src/library/scala/collection/GenTraversableLike.scala
+++ b/src/library/scala/collection/GenTraversableLike.scala
@@ -45,6 +45,7 @@ import annotation.migration
  *
  *  @define Coll GenTraversable
  *  @define coll general collection
+ *  @define collectExample
  *  @tparam A    the collection element type.
  *  @tparam Repr the actual type of the element container.
  *
@@ -160,6 +161,8 @@ trait GenTraversableLike[+A, +Repr] extends GenTraversableOnce[A] with Paralleli
   /** Builds a new collection by applying a partial function to all elements of this $coll
    *  on which the function is defined.
    *
+   *  $collectExample
+   *
    *  @param pf     the partial function which filters and maps the $coll.
    *  @tparam B     the element type of the returned collection.
    *  @tparam That  $thatinfo
@@ -193,7 +196,27 @@ trait GenTraversableLike[+A, +Repr] extends GenTraversableOnce[A] with Paralleli
    */
   def flatMap[B, That](f: A => GenTraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That
 
-  /** Concatenates this $coll with the elements of a traversable collection.
+  /** Returns a new $coll containing the elements from the left hand operand followed by the elements from the
+   *  right hand operand. The element type of the $coll is the most specific superclass encompassing
+   *  the element types of the two operands (see example).
+   *
+   * Example:
+   * {{{
+   *     scala> val a = LinkedList(1)
+   *     a: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
+   *
+   *     scala> val b = LinkedList(2)
+   *     b: scala.collection.mutable.LinkedList[Int] = LinkedList(2)
+   *
+   *     scala> val c = a ++ b
+   *     c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *
+   *     scala> val d = LinkedList('a')
+   *     d: scala.collection.mutable.LinkedList[Char] = LinkedList(a)
+   *
+   *     scala> val e = c ++ d
+   *     e: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, a)
+   * }}}
    *
    *  @param that   the traversable to append.
    *  @tparam B     the element type of the returned collection.
diff --git a/src/library/scala/collection/GenTraversableOnce.scala b/src/library/scala/collection/GenTraversableOnce.scala
index 5045d4b829..3e42e7812b 100644
--- a/src/library/scala/collection/GenTraversableOnce.scala
+++ b/src/library/scala/collection/GenTraversableOnce.scala
@@ -114,7 +114,16 @@ trait GenTraversableOnce[+A] {
    */
   def fold[A1 >: A](z: A1)(op: (A1, A1) => A1): A1
 
-  /** A syntactic sugar for out of order folding. See `fold`. */
+  /** A syntactic sugar for out of order folding. See `fold`.
+   *
+   * Example:
+   * {{{
+   *      scala> val a = LinkedList(1,2,3,4)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4)
+   *
+   *      scala> val b = (a /:\ 5)(_+_)
+   *      b: Int = 15
+   * }}}*/
   def /:\[A1 >: A](z: A1)(op: (A1, A1) => A1): A1 = fold(z)(op)
 
   /** Applies a binary operator to a start value and all elements of this $coll,
@@ -122,6 +131,21 @@ trait GenTraversableOnce[+A] {
    *
    *  Note: `/:` is alternate syntax for `foldLeft`; `z /: xs` is the same as
    *  `xs foldLeft z`.
+   *
+   *  Examples:
+   *
+   *  Note that the folding function used to compute b is equivalent to that used to compute c.
+   *  {{{
+   *      scala> val a = LinkedList(1,2,3,4)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4)
+   *
+   *      scala> val b = (5 /: a)(_+_)
+   *      b: Int = 15
+   *
+   *      scala> val c = (5 /: a)((x,y) => x + y)
+   *      c: Int = 15
+   *  }}}
+
    *  $willNotTerminateInf
    *  $orderDependentFold
    *
@@ -145,6 +169,21 @@ trait GenTraversableOnce[+A] {
    *  $willNotTerminateInf
    *  $orderDependentFold
    *
+   *  Examples:
+   *
+   *  Note that the folding function used to compute b is equivalent to that used to compute c.
+   *  {{{
+   *      scala> val a = LinkedList(1,2,3,4)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4)
+   *
+   *      scala> val b = (a :\ 5)(_+_)
+   *      b: Int = 15
+   *
+   *      scala> val c = (a :\ 5)((x,y) => x + y)
+   *      c: Int = 15
+   *
+   *  }}}
+   *
    *  @param   z    the start value
    *  @param   op   the binary operator
    *  @tparam  B    the result type of the binary operator.
diff --git a/src/library/scala/collection/TraversableLike.scala b/src/library/scala/collection/TraversableLike.scala
index 1f6c6ff0bb..e3d51fde4e 100644
--- a/src/library/scala/collection/TraversableLike.scala
+++ b/src/library/scala/collection/TraversableLike.scala
@@ -157,10 +157,22 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
   def ++[B >: A, That](that: TraversableOnce[B])(implicit bf: CanBuildFrom[Repr, B, That]): That =
     ++(that: GenTraversableOnce[B])(bf)
 
-  /** Concatenates this $coll with the elements of a traversable collection.
+  /** As with `++`, returns a new collection containing the elements from the left operand followed by the
+   *  elements from the right operand.
    *  It differs from `++` in that the right operand determines the type of
    *  the resulting collection rather than the left one.
    *
+   *  Example:
+   *  {{{
+   *     scala> val x = List(1)
+   *     x: List[Int] = List(1)
+   *
+   *     scala> val y = LinkedList(2)
+   *     y: scala.collection.mutable.LinkedList[Int] = LinkedList(2)
+   *
+   *     scala> val z = x ++: y
+   *     z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *  }}}
    *  @param that   the traversable to append.
    *  @tparam B     the element type of the returned collection.
    *  @tparam That  $thatinfo
@@ -181,12 +193,39 @@ trait TraversableLike[+A, +Repr] extends HasNewBuilder[A, Repr]
     b.result
   }
 
-  /** This overload exists because: for the implementation of `++`: we should
+  /** As with `++`, returns a new collection containing the elements from the left operand followed by the
+   *  elements from the right operand.
+   *  It differs from `++` in that the right operand determines the type of
+   *  the resulting collection rather than the left one.
+   *
+   *  Example:
+   *  {{{
+   *     scala> val x = List(1)
+   *     x: List[Int] = List(1)
+   *
+   *     scala> val y = LinkedList(2)
+   *     y: scala.collection.mutable.LinkedList[Int] = LinkedList(2)
+   *
+   *     scala> val z = x ++: y
+   *     z: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *  }}}
+   *
+   * This overload exists because: for the implementation of `++:` we should
    *  reuse that of `++` because many collections override it with more
    *  efficient versions.
    *
    *  Since `TraversableOnce` has no `++` method, we have to implement that
    *  directly, but `Traversable` and down can use the overload.
+   *
+   *  @param that   the traversable to append.
+   *  @tparam B     the element type of the returned collection.
+   *  @tparam That  $thatinfo
+   *  @param bf     $bfinfo
+   *  @return       a new collection of type `That` which contains all elements
+   *                of this $coll followed by all elements of `that`.
+   *
+   *  @return       a new $coll which contains all elements of this $coll
+   *                followed by all elements of `that`.
    */
   def ++:[B >: A, That](that: Traversable[B])(implicit bf: CanBuildFrom[Repr, B, That]): That =
     (that ++ seq)(breakOut)
diff --git a/src/library/scala/collection/TraversableOnce.scala b/src/library/scala/collection/TraversableOnce.scala
index 01619b0ab0..4f125b4090 100644
--- a/src/library/scala/collection/TraversableOnce.scala
+++ b/src/library/scala/collection/TraversableOnce.scala
@@ -271,6 +271,19 @@ trait TraversableOnce[+A] extends GenTraversableOnce[A] {
    *  Inside, the string representations (w.r.t. the method `toString`)
    *  of all elements of this $coll are separated by the string `sep`.
    *
+   * Example:
+   *
+   * {{{
+   *      scala> val a = LinkedList(1,2,3,4)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4)
+   *
+   *      scala> val b = new StringBuilder()
+   *      b: StringBuilder =
+   *
+   *      scala> a.addString(b, "LinkedList(", ", ", ")")
+   *      res1: StringBuilder = LinkedList(1, 2, 3, 4)
+   * }}}
+   *
    *  @param  b    the string builder to which elements are appended.
    *  @param start the starting string.
    *  @param sep   the separator string.
@@ -300,6 +313,19 @@ trait TraversableOnce[+A] extends GenTraversableOnce[A] {
    *  The written text consists of the string representations (w.r.t. the method `toString`)
    *  of all elements of this $coll, separated by the string `sep`.
    *
+   * Example:
+   *
+   * {{{
+   *      scala> val a = LinkedList(1,2,3,4)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4)
+   *
+   *      scala> val b = new StringBuilder()
+   *      b: StringBuilder =
+   *
+   *      scala> a.addString(b, ", ")
+   *      res0: StringBuilder = 1, 2, 3, 4
+   * }}}
+   *
    *  @param  b    the string builder to which elements are appended.
    *  @param sep   the separator string.
    *  @return      the string builder `b` to which elements were appended.
@@ -310,6 +336,19 @@ trait TraversableOnce[+A] extends GenTraversableOnce[A] {
    *  The written text consists of the string representations (w.r.t. the method
    * `toString`) of all elements of this $coll without any separator string.
    *
+   * Example:
+   *
+   * {{{
+   *      scala> val a = LinkedList(1,2,3,4)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3, 4)
+   *
+   *      scala> val b = new StringBuilder()
+   *      b: StringBuilder =
+   *
+   *      scala> val h = a.addString(b)
+   *      b: StringBuilder = 1234
+   * }}}
+
    *  @param  b    the string builder to which elements are appended.
    *  @return      the string builder `b` to which elements were appended.
    */
diff --git a/src/library/scala/collection/mutable/LinkedList.scala b/src/library/scala/collection/mutable/LinkedList.scala
index bfb2db2b34..6c4372cbb4 100644
--- a/src/library/scala/collection/mutable/LinkedList.scala
+++ b/src/library/scala/collection/mutable/LinkedList.scala
@@ -13,30 +13,65 @@ package mutable
 
 import generic._
 
-/** This class implements single linked lists where both the head (`elem`)
- *  and the tail (`next`) are mutable.
- *
- *  @author Matthias Zenger
- *  @author Martin Odersky
- *  @version 2.8
- *  @since   1
- *
- *  @tparam A     the type of the elements contained in this linked list.
- *
- *  @define Coll LinkedList
- *  @define coll linked list
- *  @define thatinfo the class of the returned collection. In the standard library configuration,
- *    `That` is always `LinkedList[B]` because an implicit of type `CanBuildFrom[LinkedList, B, LinkedList[B]]`
- *    is defined in object `LinkedList`.
- *  @define bfinfo an implicit value of class `CanBuildFrom` which determines the
- *    result class `That` from the current representation type `Repr`
- *    and the new element type `B`. This is usually the `canBuildFrom` value
- *    defined in object `LinkedList`.
- *  @define orderDependent
- *  @define orderDependentFold
- *  @define mayNotTerminateInf
- *  @define willNotTerminateInf
- */
+/** A more traditional/primitive style of linked list where the "list" is also the "head" link. Links can be manually
+  * created and manipulated, though the use of the API, when possible, is recommended.
+  *
+  * The danger of directly manipulating next:
+  * {{{
+  *     scala> val b = LinkedList(1)
+  *     b: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
+  *
+  *     scala> b.next = null
+  *
+  *     scala> println(b)
+  *     java.lang.NullPointerException
+  * }}}
+  *
+  *  $singleLinkedListExample
+  *
+  *  @author Matthias Zenger
+  *  @author Martin Odersky
+  *  @version 2.8
+  *  @since   1
+  *
+  *  @tparam A     the type of the elements contained in this linked list.
+  *
+  *  @constructor Creates an "empty" list, defined as a single node with no data element and next pointing to itself.
+
+  *  @define Coll LinkedList
+  *  @define coll linked list
+  *  @define thatinfo the class of the returned collection. In the standard library configuration,
+  *    `That` is always `LinkedList[B]` because an implicit of type `CanBuildFrom[LinkedList, B, LinkedList[B]]`
+  *    is defined in object `LinkedList`.
+  *  @define bfinfo an implicit value of class `CanBuildFrom` which determines the
+  *    result class `That` from the current representation type `Repr`
+  *    and the new element type `B`. This is usually the `canBuildFrom` value
+  *    defined in object `LinkedList`.
+  *  @define orderDependent
+  *  @define orderDependentFold
+  *  @define mayNotTerminateInf
+  *  @define willNotTerminateInf
+  *  @define collectExample Example:
+  *  {{{
+  *    scala>     val a = LinkedList(1, 2, 3)
+  *    a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 3)
+  *
+  *    scala>     val addOne: PartialFunction[Any, Float] = {case i: Int => i + 1.0f}
+  *    addOne: PartialFunction[Any,Float] = <function1>
+  *
+  *    scala>     val b = a.collect(addOne)
+  *    b: scala.collection.mutable.LinkedList[Float] = LinkedList(2.0, 3.0, 4.0)
+  *
+  *    scala> val c = LinkedList('a')
+  *    c: scala.collection.mutable.LinkedList[Char] = LinkedList(a)
+  *
+  *    scala> val d = a ++ c
+  *    d: scala.collection.mutable.LinkedList[AnyVal] = LinkedList(1, 2, 3, a)
+  *
+  *    scala> val e = d.collect(addOne)
+  *    e: scala.collection.mutable.LinkedList[Float] = LinkedList(2.0, 3.0, 4.0)
+  *  }}}
+  */
 @SerialVersionUID(-7308240733518833071L)
 class LinkedList[A]() extends LinearSeq[A]
                          with GenericTraversableTemplate[A, LinkedList]
@@ -44,6 +79,21 @@ class LinkedList[A]() extends LinearSeq[A]
                          with Serializable {
   next = this
 
+  /** Creates a new list. If the parameter next is null, the result is an empty list. Otherwise, the result is
+   * a list with elem at the head, followed by the contents of next.
+   *
+   * Note that next is part of the new list, as opposed to the +: operator,
+   * which makes a new copy of the original list.
+   *
+   * @example
+   * {{{
+   *     scala> val m = LinkedList(1)
+   *     m: scala.collection.mutable.LinkedList[Int] = LinkedList(1)
+   *
+   *     scala> val n = new LinkedList[Int](2, m)
+   *     n: scala.collection.mutable.LinkedList[Int] = LinkedList(2, 1)
+   * }}}
+   */
   def this(elem: A, next: LinkedList[A]) {
     this()
     if (next != null) {
diff --git a/src/library/scala/collection/mutable/LinkedListLike.scala b/src/library/scala/collection/mutable/LinkedListLike.scala
index a3fd786c2a..0f977c0a17 100644
--- a/src/library/scala/collection/mutable/LinkedListLike.scala
+++ b/src/library/scala/collection/mutable/LinkedListLike.scala
@@ -19,6 +19,20 @@ import annotation.tailrec
  *  list, type variable `This` is used to model self types of
  *  linked lists.
  *
+ *  $singleLinkedListExample
+ *
+ *  @author  Matthias Zenger
+ *  @author  Martin Odersky
+ *  @version 1.0, 08/07/2003
+ *  @since   2.8
+ *
+ *  @tparam A    type of the elements contained in the linked list
+ *  @tparam This the type of the actual linked list holding the elements
+ *
+ *  @define Coll LinkedList
+ *  @define coll linked list
+ *
+ *  @define singleLinkedListExample
  *  If the list is empty `next` must be set to `this`. The last node in every
  *  mutable linked list is empty.
  *
@@ -42,17 +56,6 @@ import annotation.tailrec
  *                                   [   ] <-`
  *
  *  }}}
- *
- *  @author  Matthias Zenger
- *  @author  Martin Odersky
- *  @version 1.0, 08/07/2003
- *  @since   2.8
- *
- *  @tparam A    type of the elements contained in the linked list
- *  @tparam This the type of the actual linked list holding the elements
- *
- *  @define Coll LinkedList
- *  @define coll linked list
  */
 trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends SeqLike[A, This] { self =>
 
@@ -60,6 +63,10 @@ trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends Seq
   var next: This = _
 
   override def isEmpty = next eq this
+
+  /** Determines the length of this $coll by traversing and counting every
+    * node.
+    */
   override def length: Int = length0(repr, 0)
 
   @tailrec private def length0(elem: This, acc: Int): Int =
@@ -74,7 +81,39 @@ trait LinkedListLike[A, This <: Seq[A] with LinkedListLike[A, This]] extends Seq
     next
   }
 
-  /** Append linked list `that` at current position of this linked list
+  /** If `this` is empty then it does nothing and returns `that`. Otherwise, appends `that` to `this`. The append
+   * requires a full traversal of `this`.
+   *
+   * Examples:
+   *
+   * {{{
+   *      scala> val a = LinkedList(1, 2)
+   *      a: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *
+   *      scala> val b = LinkedList(1, 2)
+   *      b: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *
+   *      scala> a.append(b)
+   *      res0: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2, 1, 2)
+   *
+   *      scala> println(a)
+   *      LinkedList(1, 2, 1, 2)
+   * }}}
+   *
+   * {{{
+   *    scala> val a = new LinkedList[Int]()
+   *    a: scala.collection.mutable.LinkedList[Int] = LinkedList()
+   *
+   *    scala> val b = LinkedList(1, 2)
+   *    b: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *
+   *    scala> val c = a.append(b)
+   *    c: scala.collection.mutable.LinkedList[Int] = LinkedList(1, 2)
+   *
+   *    scala> println(a)
+   *    LinkedList()
+   * }}}
+   *
    *  @return the list after append (this is the list itself if nonempty,
    *  or list `that` if list this is empty. )
    */