improved scaladoc comments in List, collection....

improved scaladoc comments in List, collection.Map, etc.

4 files changed, 97 insertions, 60 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
index 9216c2149e..72dab71d7f 100644
--- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
+++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
@@ -1151,7 +1151,9 @@ abstract class DocGenerator extends Models {
       "Predef.NoSuchElementException" ->
         Pair(definitions.PredefModule, "NoSuchElementException") +
       "Predef.NullPointerException" ->
-        Pair(definitions.PredefModule, "NullPointerException")
+        Pair(definitions.PredefModule, "NullPointerException") +
+      "Predef.UnsupportedOperationException" ->
+        Pair(definitions.PredefModule, "UnsupportedOperationException")
     val body = buf.toString
     if (isShort) <span>{parse(body)}</span>;
     else <span><dl><dd>{parse(body)}</dd></dl><dl>
diff --git a/src/library/scala/List.scala b/src/library/scala/List.scala
index fcf6c1d680..912a2c2468 100644
--- a/src/library/scala/List.scala
+++ b/src/library/scala/List.scala
@@ -96,10 +96,11 @@ object List {
   /** Create a list by applying a function to successive integers.
    *
    *  @param n     the length of the resulting list
-   *  @param maker the procedure which, given an integer n, returns the
-   *               nth element of the resulting list, where n is in [0;n).
-   *  @return the list obtained by applying the maker function to successive
-   *          integers from 0 to n (exclusive).
+   *  @param maker the procedure which, given an integer <code>n</code>,
+   *               returns the nth element of the resulting list, where
+   *               <code>n</code> is in interval <code>[0;n)</code>.
+   *  @return      the list obtained by applying the maker function to
+   *               successive integers from 0 to n (exclusive).
    */
   def tabulate[a](n: Int, maker: Int => a): List[a] = {
     val b = new ListBuffer[a]
@@ -208,7 +209,7 @@ object List {
   /** Returns the given string as a list of characters.
    *
    *  @param str the string to convert.
-   *  @return the string as a list of characters.
+   *  @return    the string as a list of characters.
    */
   def fromString(str: String): List[Char] =
     Iterator.fromString(str).toList
@@ -216,7 +217,7 @@ object List {
   /** Returns the given list of characters as a string.
    *
    *  @param xs the list to convert.
-   *  @return the list in form of a string.
+   *  @return   the list in form of a string.
    */
   def toString(xs: List[Char]): String = {
     val sb = new compat.StringBuilder()
@@ -306,8 +307,10 @@ object List {
    *  for all corresponding elements of the argument lists.
    *
    *  @param p function to apply to each pair of elements.
-   *  @return <code>n == 0 || (p(a0,b0) &amp;&amp; ... &amp;&amp; p(an,bn))]</code>
-   *          if the lists are <code>[a0, ..., ak]</code>, <code>[b0, ..., bl]</code>
+   *  @return  <code>n == 0 || (p(a<sub>0</sub>,b<sub>0</sub>) &amp;&amp;
+   *           ... &amp;&amp; p(a<sub>n</sub>,b<sub>n</sub>))]</code>
+   *           if the lists are <code>[a<sub>0</sub>, ..., a<sub>k</sub>]</code>;
+   *           <code>[b<sub>0</sub>, ..., b<sub>l</sub>]</code>
    *          and <code>m = min(k,l)</code>
    */
   def forall2[a,b](xs: List[a], ys: List[b])(f: (a, b) => boolean): boolean = {
@@ -759,15 +762,22 @@ sealed abstract class List[+a] extends Seq[a] {
     Pair(btrue.toList, bfalse.toList)
   }
 
-  /** Sort the list according to the comparison function
-   *  <code>&lt;(e1: a, e2: a) =&gt; Boolean</code>,
-   *  which should be true iff e1 is smaller than e2.
-   *  Note: The current implementation is inefficent for
-   *  already sorted lists.
+  /** <p>
+   *    Sort the list according to the comparison function
+   *    <code>&lt;(e1: a, e2: a) =&gt; Boolean</code>,
+   *    which should be true iff <code>e1</code> is smaller than
+   *    <code>e2</code>. Example:
+   *  </p>
+   *  <pre>List("Tom", "John", "Bob").sort(
+   *    (e1, e2) => (e1 compareTo e2) &lt; 0)</pre>
+   *  <p>
+   *    Note: The current implementation is inefficent for
+   *    already sorted lists.
+   *  </p>
    *
    *  @param lt the comparison function
-   *  @return a list sorted according to the comparison function
-   *          <code>&lt;(e1: a, e2: a) =&gt; Boolean</code>.
+   *  @return   a list sorted according to the comparison function
+   *            <code>&lt;(e1: a, e2: a) =&gt; Boolean</code>.
    */
   def sort(lt : (a,a) => Boolean): List[a] = {
     def sort_1(smaller: List[a], acc: List[a]): List[a] =
@@ -835,7 +845,8 @@ sealed abstract class List[+a] extends Seq[a] {
    *  in this list.
    *
    *  @param p the test predicate.
-   *  @return True iff all elements of this list satisfy the predicate <code>p</code>.
+   *  @return  <code>true</code> iff all elements of this list satisfy the
+   *           predicate <code>p</code>.
    */
   override def forall(p: a => Boolean): Boolean = {
     var these = this
@@ -850,8 +861,8 @@ sealed abstract class List[+a] extends Seq[a] {
    * <code>p</code>.
    *
    *  @param p the test predicate.
-   *  @return true iff there exists an element in this list that satisfies
-   *  the predicate <code>p</code>.
+   *  @return  <code>true</code> iff there exists an element in this list that
+   *           satisfies the predicate <code>p</code>.
    */
   override def exists(p: a => Boolean): Boolean = {
     var these = this
@@ -891,8 +902,9 @@ sealed abstract class List[+a] extends Seq[a] {
    *  function <code>f</code>, from left to right, and starting with
    *  the value <code>z</code>.
    *
-   *  @return <code>f(... (f(f(z, a0), a1) ...), an)</code> if the list
-   *  is <code>[a0, a1, ..., an]</code>.
+   *  @return <code>f(... (f(f(z, a<sub>0</sub>), a<sub>1</sub>) ...),
+   *          a<sub>n</sub>)</code> if the list is
+   *          <code>[a<sub>0</sub>, a<sub>1</sub>, ..., a<sub>n</sub>]</code>.
    */
   override def foldLeft[b](z: b)(f: (b, a) => b): b = {
     var acc = z
@@ -908,19 +920,27 @@ sealed abstract class List[+a] extends Seq[a] {
    *  function <code>f</code>, from rigth to left, and starting with
    *  the value <code>z</code>.
    *
-   *  @return <code>f(a0, f(a1, f(..., f(an, z)...)))</code> if the list
-   *  is <code>[a0, a1, ..., an]</code>.
+   *  @return <code>f(a<sub>0</sub>, f(a<sub>1</sub>, f(..., f(a<sub>n</sub>, z)...)))</code>
+   *          if the list is <code>[a<sub>0</sub>, a1, ..., an]</code>.
    */
   override def foldRight[b](z: b)(f: (a, b) => b): b = this match {
     case Nil => z
     case x :: xs => f(x, xs.foldRight(z)(f))
   }
 
+  /**
+   *  @return ...
+   *  @throws Predef.UnsupportedOperationException ...
+   */
   def reduceLeft[b >: a](f: (b, b) => b): b = this match {
     case Nil => throw new UnsupportedOperationException("Nil.reduceLeft")
     case x :: xs => ((xs: List[b]) foldLeft (x: b))(f)
   }
 
+  /**
+   *  @return ...
+   *  @throws Predef.UnsupportedOperationException ...
+   */
   def reduceRight[b >: a](f: (b, b) => b): b = this match {
     case Nil => throw new UnsupportedOperationException("Nil.reduceRight")
     case x :: Nil => x: b
@@ -949,12 +969,9 @@ sealed abstract class List[+a] extends Seq[a] {
   }
 
   /** <p>
-   *    Reverses the elements of this list.
-   *  </p>
-   *  <p>
-   *    Example:
+   *    Reverses the elements of this list. Example:
    *  </p>
-   *  <code>[1, 2, 3] reverse = [3, 2, 1]</code>.
+   *  <pre>List(1, 2, 3) reverse = List(3, 2, 1)</pre>
    *
    *  @return the elements of this list in reverse order.
    */
@@ -965,9 +982,12 @@ sealed abstract class List[+a] extends Seq[a] {
    *  <code>that</code> by associating each element of the former with
    *  the element at the same position in the latter.
    *
-   *  @param that <code>that</code> must have the same length as the self list.
-   *  @return     <code>[(a0,b0), ..., (an,bn)]</code> when
-   *              <code>[a0, ..., an] zip [b0, ..., bn]</code> is invoked.
+   *  @param that list <code>that</code> must have the same length as the
+   *              self list.
+   *  @return     <code>[(a<sub>0</sub>,b<sub>0</sub>), ...,
+   *              (a<sub>n</sub>,b<sub>n</sub>)]</code> when
+   *              <code>[a<sub>0</sub>, ..., a<sub>n</sub>]
+   *              zip [b<sub>0</sub>, ..., b<sub>n</sub>]</code> is invoked.
    */
   def zip[b](that: List[b]): List[Pair[a,b]] = {
     val b = new ListBuffer[Pair[a, b]]
@@ -985,8 +1005,10 @@ sealed abstract class List[+a] extends Seq[a] {
     *  with its index, counting from 0.
     *
     *  @param start the index of the first element
-    *  @return      an iterator yielding <code>(a0,0), (a0,1)...</code>
-    *               where <code>ai</code> are the elements from this iterator.
+    *  @return      an iterator yielding <code>(a<sub>0</sub>,0),
+    *               (a<sub>0</sub>,1)...</code>
+    *               where <code>a<sub>i</sub></code> are the elements from
+    *               this iterator.
     */
   def zipWithIndex = {
     val b = new ListBuffer[Pair[a,int]]
@@ -1014,7 +1036,9 @@ sealed abstract class List[+a] extends Seq[a] {
    *  @param thatElem element <code>thatElem</code> is used to fill up the
    *                  resulting list if <code>that</code> is shorter than
    *                  the self list
-   *  @return         <code>[(a0,b0), ..., (an,bn), (elem,bn+1), ..., (elem,bm)]</code>
+   *  @return         <code>[(a<sub>0</sub>,b<sub>0</sub>), ...,
+   *                  (a<sub>n</sub>,b<sub>n</sub>), (elem,b<sub>n+1</sub>),
+   *                  ..., (elem,b<sub>m</sub>)]</code>
    *                  when <code>[a0, ..., an] zip [b0, ..., bm]</code> is
    *                  invoked where <code>m &gt; n</code>.
    */
diff --git a/src/library/scala/collection/Map.scala b/src/library/scala/collection/Map.scala
index 842544b3a4..211158f047 100644
--- a/src/library/scala/collection/Map.scala
+++ b/src/library/scala/collection/Map.scala
@@ -16,10 +16,12 @@ package scala.collection
 
 /** This class defines the interface of collections that unambiguously map
  *  keys to values (i.e. a key is mapped to at least one value).
- *  Class <code>Map</code> may only be used for
- *  accessing elements from map implementations. Two different extensions
- *  of class <code>Map</code> in the package <code>scala.collections.mutable</code>
- *  and  <code>scala.collections.immutable</code> provide functionality for
+ *  Class <code>Map</code> may only be used for accessing elements from map
+ *  implementations. Two different extensions of class <code>Map</code> in
+ *  the package <code><a href="mutable$content.html" target="contentFrame">
+ *  scala.collection.mutable</a></code>
+ *  and  <code><a href="immutable$content.html" target="contentFrame">
+ *  scala.collection.immutable</a></code> provide functionality for
  *  adding new key/value mappings to a map. The class in the first package is
  *  implemented by maps that are modified destructively, whereas the class in
  *  the second package is used by functional map implementations that rely on
@@ -41,14 +43,14 @@ trait Map[A, +B] extends AnyRef
     /** Check if this map maps <code>key</code> to a value and return the
      *  value if it exists.
      *
-     *  @param  key     the key of the mapping of interest
-     *  @return the value of the mapping, if it exists
+     *  @param  key the key of the mapping of interest
+     *  @return     the value of the mapping, if it exists
      */
     def get(key: A): Option[B]
 
     /** Is this an empty map?
      *
-     *  @return true, iff the map is empty.
+     *  @return <code>true</code> iff the map is empty.
      */
     def isEmpty: Boolean = (size == 0)
 
@@ -56,8 +58,8 @@ trait Map[A, +B] extends AnyRef
      *  method throws an exception if there is no mapping from the given
      *  key to a value.
      *
-     *  @param  key     the key
-     *  @return the value associated with the given key.
+     *  @param  key the key
+     *  @return     the value associated with the given key.
      */
     def apply(key: A): B = get(key) match {
       case None => default(key)
@@ -66,8 +68,8 @@ trait Map[A, +B] extends AnyRef
 
     /** Is the given key mapped to a value by this map?
      *
-     *  @param   key        the key
-     *  @return true, iff there is a mapping for key in this map
+     *  @param key the key
+     *  @return    <code>true</code> iff there is a mapping for key in this map
      */
     def contains(key: A): Boolean = get(key) match {
       case None => false
@@ -76,8 +78,8 @@ trait Map[A, +B] extends AnyRef
 
     /** Does this map contain a mapping from the given key to a value?
      *
-     *  @param   key        the key
-     *  @return true, iff there is a mapping for key in this map
+     *  @param key the key
+     *  @return    <code>true</code> iff there is a mapping for key in this map
      */
     def isDefinedAt(key: A) = contains(key)
 
@@ -105,7 +107,9 @@ trait Map[A, +B] extends AnyRef
      *  contained in this map are also contained in the other map,
      *  and vice versa.
      *
-     *  @return    true, iff both maps contain exactly the same mappings.
+     *  @param that the other map
+     *  @return     <code>true</code> iff both maps contain exactly the
+     *              same mappings.
      */
     override def equals(that: Any): Boolean = that match {
       case other: Map[a, b] =>
@@ -140,6 +144,7 @@ trait Map[A, +B] extends AnyRef
      *  but it might be overridden in subclasses.
      *
      *  @param key ...
+     *  @throws Predef.NoSuchElementException ...
      */
     def default(key: A): B =
       throw new NoSuchElementException("key not found: " + key)
diff --git a/src/library/scala/collection/Set.scala b/src/library/scala/collection/Set.scala
index 107a1948d6..0fd60805af 100644
--- a/src/library/scala/collection/Set.scala
+++ b/src/library/scala/collection/Set.scala
@@ -15,8 +15,11 @@ package scala.collection
 /** This class defines the interface of collections that do not contain
  *  duplicate elements. Class <code>Set</code> may only be used for
  *  accessing elements from set implementations. Two different extensions
- *  of class <code>Set</code> in the package <code>scala.collections.mutable</code>
- *  and  <code>scala.collections.immutable</code> provide functionality for
+ *  of class <code>Set</code> in the package
+ *  <code><a href="mutable$content.html" target="contentFrame">
+ *  scala.collection.mutable</a></code> and
+ *  <code><a href="immutable$content.html" target="contentFrame">
+ *  scala.collection.immutable</a></code> provide functionality for
  *  adding new elements to a set. The class in the first package is implemented
  *  by sets the are modified destructively, whereas the class in the second
  *  package is used by functional set implementations that rely on immutable
@@ -35,29 +38,32 @@ trait Set[A] extends AnyRef with Function1[A, Boolean] with Iterable[A] {
 
     /** Checks if this set contains element <code>elem</code>.
      *
-     *  @param  elem    the element to check for membership.
-     *  @return true, iff <code>elem</code> is contained in this set.
+     *  @param elem the element to check for membership.
+     *  @return     <code>true</code> iff <code>elem</code> is contained ini
+     *              this set.
      */
     def contains(elem: A): Boolean
 
     /** This method allows sets to be interpreted as predicates.
      *  It returns true, iff this set contains element <code>elem</code>.
      *
-     *  @param  elem    the element to check for membership.
-     *  @return true, iff <code>elem</code> is contained in this set.
+     *  @param elem the element to check for membership.
+     *  @return     <code>true</code> iff <code>elem</code> is contained in
+     *              this set.
      */
     def apply(elem: A): Boolean = contains(elem)
 
     /** Checks if this set is empty.
      *
-     *  @return true, iff there is no element in the set.
+     *  @return <code>true</code> iff there is no element in the set.
      */
     def isEmpty: Boolean = (size == 0)
 
     /** Checks if this set is a subset of set <code>that</code>.
      *
-     *  @param  that another set.
-     *  @return true, iff the other set is a superset of this set.
+     *  @param that another set.
+     *  @return     <code>true</code> iff the other set is a superset of
+     *              this set.
      */
     def subsetOf(that: Set[A]): Boolean = forall(that.contains)
 
@@ -65,9 +71,9 @@ trait Set[A] extends AnyRef with Function1[A, Boolean] with Iterable[A] {
      *  other object is also a set which contains the same elements as
      *  this set.
      *
-     *  @param  that  the other object
-     *  @return true, iff this set and the other set contain the same
-     *          elements.
+     *  @param that the other object
+     *  @return     <code>true</code> iff this set and the other set
+     *              contain the same elements.
      */
     override def equals(that: Any): Boolean = that match {
       case other: Set[a] =>