improved comments in scala/collection/*.scala

18 files changed, 260 insertions, 142 deletions

diff --git a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
index ce7287697f..5bf30e518e 100644
--- a/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
+++ b/src/compiler/scala/tools/nsc/doc/DocGenerator.scala
@@ -296,21 +296,23 @@ abstract class DocGenerator extends Models {
      *  @param mmbr ...
      *  @return     ...
      */
-    def listSubclasses(mmbr: HasTree): NodeSeq =
-      if (!subclasses(mmbr.tree.symbol).isEmpty)
+    def listSubclasses(mmbr: HasTree): NodeSeq = {
+      val subcs = subclasses(mmbr.tree.symbol)
+      if (subcs.isEmpty)
+        NodeSeq.Empty
+      else
         <dl>
           <dt style="margin:10px 0 0 20px;">
             <b>Direct known subclasses:</b>
           </dt>
           <dd>{ {
             val links =
-              for (val subc <- subclasses(mmbr.tree.symbol)) yield
+              for (val subc <- subcs) yield
                 aref(urlFor(subc), contentFrame, subc.nameString)
             links.reduceRight { (link: Seq[Node], seq: Seq[Node]) => link.concat(Text(", ")).concat(seq) }
           } }</dd>
         </dl>;
-      else
-        NodeSeq.Empty
+    }
 
     def lists(mmbr: HasTree) = mmbr match {
       case cmod: ImplMod => <span>{ listMembersShort(mmbr) }
@@ -578,18 +580,19 @@ abstract class DocGenerator extends Models {
     for (val unit <- units) {
       val sourceMod = new SourceMod(unit)
       for (val mmbr <- sourceMod.members) mmbr.tree match {
-        case cdef:  ImplDef =>
+        case cdef: ImplDef =>
           assert(cdef.symbol.owner != NoSymbol)
           val sym = cdef.symbol.owner.asInstanceOf[ModuleClassSymbol]
           if (!sym.isEmptyPackageClass) {
-            if (!topLevel.contains(sym)) topLevel = topLevel.update(sym, emptyMap)
+            if (!topLevel.contains(sym))
+              topLevel = topLevel.update(sym, emptyMap)
             topLevel = topLevel.update(sym, organize0(mmbr, topLevel(sym)))
           }
           for (val p <- cdef.symbol.info.parents) {
             subclasses(p.symbol) = cdef.symbol :: subclasses(p.symbol)
           }
-          import Flags._;
-          val mmbrs = cdef.symbol.info.findMember(nme.ANYNAME, MUTABLE | METHOD | BRIDGE | ACCESSOR, 0, false).alternatives;
+          import Flags._
+          val mmbrs = cdef.symbol.info.findMember(nme.ANYNAME, MUTABLE | METHOD | BRIDGE | ACCESSOR, 0, false).alternatives
           for (val c <- mmbrs; c.isClass)
             for (val p <- c.info.parents) {
               subclasses(p.symbol) = c :: subclasses(p.symbol)
diff --git a/src/library/scala/collection/BitSet.scala b/src/library/scala/collection/BitSet.scala
index 3bbb7e4ebf..d6607058cf 100644
--- a/src/library/scala/collection/BitSet.scala
+++ b/src/library/scala/collection/BitSet.scala
@@ -15,7 +15,7 @@ package scala.collection
 /** <p>
  *    The class <code>BitSet</code> provides the interface for a space-efficient
  *    implementation of dense integer sets represented as bits in array of
- *    integers. Bit indices are between 0..(capacity-1) inclusive.
+ *    integers. Bit indices are between <code>0..(capacity-1)</code> inclusive.
  *  </p>
  *
  *  @author  Burak Emir, Stephane Micheloud, Nikolay Mihaylov
diff --git a/src/library/scala/collection/MapProxy.scala b/src/library/scala/collection/MapProxy.scala
index d780c9ed65..54aeccde36 100644
--- a/src/library/scala/collection/MapProxy.scala
+++ b/src/library/scala/collection/MapProxy.scala
@@ -12,7 +12,8 @@
 package scala.collection
 
 
-/** This is a simple wrapper class for <code>scala.collection.Map</code>.
+/** This is a simple wrapper class for <a href="Map.html"
+ *  target="contentFrame"><code>scala.collection.Map</code></a>.
  *  It is most useful for assembling customized map abstractions
  *  dynamically using object composition and forwarding.
  *
diff --git a/src/library/scala/collection/SetProxy.scala b/src/library/scala/collection/SetProxy.scala
index 41d2d13b35..4d770daec9 100644
--- a/src/library/scala/collection/SetProxy.scala
+++ b/src/library/scala/collection/SetProxy.scala
@@ -12,7 +12,8 @@
 package scala.collection
 
 
-/** This is a simple wrapper class for <code>scala.collection.Set</code>.
+/** This is a simple wrapper class for <a href="Set.html"
+ *  target="contentFrame"><code>scala.collection.Set</code></a>.
  *  It is most useful for assembling customized set abstractions
  *  dynamically using object composition and forwarding.
  *
diff --git a/src/library/scala/collection/immutable/BitSet.scala b/src/library/scala/collection/immutable/BitSet.scala
index 2e16c68322..1f3af38ee0 100644
--- a/src/library/scala/collection/immutable/BitSet.scala
+++ b/src/library/scala/collection/immutable/BitSet.scala
@@ -12,9 +12,9 @@
 package scala.collection.immutable
 
 
-/** The class <code>BitSet</code>provides an immutable bitset view on an
+/** The class <code>BitSet</code> provides an immutable bitset view on an
  *  int array. Instances can conveniently be created from instances of
- *  Bit indices are between 0..(capacity-1) inclusive
+ *  Bit indices are between <code>0..(capacity-1)</code> inclusive.
  *
  *  @param size     <code>size</code> represents the number of relevant bits
  *  @param capacity ...
@@ -33,7 +33,7 @@ class BitSet(val size: Int, val capacity: Int, ba: Array[Int], copy: Boolean)
 {
   import compat.Platform.arraycopy
 
-  protected val arr: Array[Int]  =
+  protected val arr: Array[Int] =
     if (copy) {
       val arr = new Array[Int](ba.length)
       arraycopy(ba, 0, arr, 0, ba.length)
diff --git a/src/library/scala/collection/immutable/Map.scala b/src/library/scala/collection/immutable/Map.scala
index 3841681a71..787d5d1670 100644
--- a/src/library/scala/collection/immutable/Map.scala
+++ b/src/library/scala/collection/immutable/Map.scala
@@ -12,13 +12,21 @@
 package scala.collection.immutable
 
 
-/** This class extends the Map interface of collections that unambiguously map
- *  keys to values (i.e. a key is mapped to at least one value).
- *  This class defines the interface for functional map implementations
- *  relying on immutable data structures.
- *  Concrete map implementations have to provide functionality for the
- *  abstract methods in scala.collection.Map as well as for
- *  <code>factory</code>, <code>update</code>, and -.
+/** <p>
+ *    This class extends the <code>Map</code> interface of collections
+ *    that unambiguously map keys to values (i.e. a key is mapped to at
+ *    least one value).
+ *  </p>
+ *  <p>
+ *    This class defines the interface for functional map implementations
+ *    relying on immutable data structures.
+ *  </p>
+ *  <p>
+ *    Concrete map implementations have to provide functionality for
+ *    the abstract methods in <a href="../Map.html" target="contentFrame">
+ *    <code>scala.collection.Map</code></a> as well as for
+ *    <code>factory</code>, <code>update</code>, and <code>-</code>.
+ *  </p>
  *
  *  @author  Matthias Zenger
  *  @author  Erik Stenman
@@ -36,6 +44,10 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
    *  to <code>value</code>. If the map contains already a
    *  mapping for <code>key</code>, it will be overridden by this
    *  function.
+   *
+   *  @param key   ...
+   *  @param value ...
+   *  @return      the created map
    */
   def update(key: A, value: B): Map[A, B]
 
@@ -45,10 +57,12 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
    */
   def -(key: A): Map[A, B]
 
-  /** This method defines syntactic sugar for adding a
-   *  mapping. It is typically used in the following way:
+  /** <p>
+   *    This method defines syntactic sugar for adding a
+   *    mapping. It is typically used in the following way:
+   *  </p>
    *  <pre>
-   *  map + key -> value;
+   *    map + key -> value
    *  </pre>
    */
   def +(key: A): MapTo = new MapTo(key)
@@ -57,6 +71,9 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
    *  to the map. The method assumes that a mapping is represented
    *  by a <code>Pair</code> object who's first component denotes the
    *  key, and who's second component refers to the value.
+   *
+   *  @param mappings ...
+   *  @return         ...
    */
   def incl(mappings: Pair[A, B]*): Map[A, B] = incl(mappings)
 
@@ -81,6 +98,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
    *  for the given sequence of keys are removed from the map.
    *
    *  @param keys ...
+   *  @return     the updated map
    */
   def excl(keys: A*): Map[A, B] = excl(keys)
 
@@ -88,6 +106,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
    *  iterator over the elements of the <code>keys</code> object.
    *
    *  @param keys ...
+   *  @return     the updated map
    */
   def excl(keys: Iterable[A]): Map[A, B] = {
     val iter = keys.elements
@@ -102,6 +121,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
    *  in this map with function <code>f</code>.
    *
    *  @param f A function over key-value pairs
+   *  @return  the updated map
    */
   def map[C](f: Pair[A, B] => C): Map[A, C] = {
     var res = empty[C]
@@ -114,6 +134,7 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
    *  <code>p</code> returns <code>false</code>.
    *
    *  @param p A prediacte over key-value pairs
+   *  @return  the updated map
    */
   def filter(p: Pair[A, B] => Boolean): Map[A, B] = {
     var res = this
@@ -144,6 +165,9 @@ trait Map[A, B] extends AnyRef with collection.Map[A, B] {
 
   /** This method controls how a mapping is represented in the string
    *  representation provided by method <code>toString</code>.
+   *
+   *  @param p ...
+   *  @return  the string representation of a map entry
    */
   def mappingToString(p: Pair[A, B]) = p._1.toString() + " -> " + p._2
 
diff --git a/src/library/scala/collection/immutable/Tree.scala b/src/library/scala/collection/immutable/Tree.scala
index 5f2673156a..96311936ba 100644
--- a/src/library/scala/collection/immutable/Tree.scala
+++ b/src/library/scala/collection/immutable/Tree.scala
@@ -41,19 +41,29 @@ package scala.collection.immutable
 
 import java.util.NoSuchElementException
 
-/** General Balanced Trees - highly efficient functional dictionaries.
- *
- *  <p>An efficient implementation of Prof. Arne Andersson's General
- *  Balanced Trees. These have no storage overhead compared to plain
- *  unbalanced binary trees, and their performance is in general better
- *  than AVL trees.</p>
- *  <p>This implementation does not balance the trees after deletions.
- *  Since deletions don't increase the height of a tree, this should
- *  be OK in most applications. A balance method is provided for those
- *  cases where rebalancing is needed.</p>
- *  <p>The tree consists of entries conatining a key with an order.</p>
- *  <p>When instanciating the tree an order for the keys has to be
- *  supplied.</p>
+/** <p>
+ *    General Balanced Trees - highly efficient functional dictionaries.
+ *  </p>
+ *  <p>
+ *    An efficient implementation of Prof. Arne Andersson's
+ *    <a href="http://citeseer.ist.psu.edu/andersson99general.html"
+ *    target="_top">General Balanced Trees</a>. These have no storage overhead
+ *    compared to plain unbalanced binary trees, and their performance is in
+ *    general better than AVL trees.
+ *  </p>
+ *  <p>
+ *    This implementation does not balance the trees after deletions.
+ *    Since deletions don't increase the height of a tree, this should
+ *    be OK in most applications. A balance method is provided for those
+ *    cases where rebalancing is needed.
+ *  </p>
+ *  <p>
+ *    The tree consists of entries conatining a key with an order.
+ *  </p>
+ *  <p>
+ *    When instanciating the tree an order for the keys has to be
+ *    supplied.
+ *  </p>
  *
  *  @author  Erik Stenman, Michel Schinz
  *  @version 1.1, 2005-01-20
@@ -92,18 +102,21 @@ abstract class Tree[A <% Ordered[A], B]() extends AnyRef {
    */
   protected def tree: aNode = GBLeaf[A,B]()
 
-  /** This abstract method should be defined by a concrete implementation
-   *   C[T] as something like:
-   *    <pre>
-   *     override def New(sz:Int,t:aNode):This {
-   *       new C[T](order) {
-   *        override def size=sz;
-   *        override protected def tree:aNode=t;
-   *     }
-   *    </pre>
-   *   The concrete implementation should also override the def of This
-   *   <code>override type This = C[T];</code>
-   *
+  /** <p>
+   *    This abstract method should be defined by a concrete implementation
+   *    <code>C[T]</code> as something like:
+   *  </p>
+   *  <pre>
+   *    <b>override def</b> New(sz: Int, t: aNode): This {
+   *      <b>new</b> C[T](order) {
+   *        <b>override def</b> size = sz
+   *        <b>override protected def</b> tree: aNode = t
+   *    }
+   *  </pre>
+   *  <p>
+   *     The concrete implementation should also override the def of This
+   *     <code>override type This = C[T];</code>
+   *  </p>
    */
   protected def New(sz: Int, t: aNode): This
 
@@ -157,8 +170,8 @@ abstract class Tree[A <% Ordered[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
    */
   protected def findValue(key: A): Option[B] =
     tree.get(key)
@@ -360,7 +373,11 @@ private case class GBNode[A <% Ordered[A],B](key: A,
       Triple(key1, value1, GBNode(key, value, smaller1, bigger))
   }
 
-  def balance(s:int): GBTree[A,B] =
+  /**
+   *  @param s ...
+   *  @return  ...
+   */
+  def balance(s: int): GBTree[A,B] =
     balance_list(toList(scala.Nil), s)
 
   protected def balance_list(list: List[Pair[A,B]], s: int): GBTree[A,B] = {
@@ -374,12 +391,11 @@ private case class GBNode[A <% Ordered[A],B](key: A,
         val Pair(t2, l2) = bal(l1, s2)
         val t = GBNode(k, v, t1, t2)
         Pair(t, l2)
+      } else if (s == 1) {
+        val Pair(k,v) :: rest = list
+        Pair(GBNode(k, v, empty, empty), rest)
       } else
-        if (s == 1) {
-          val Pair(k,v) :: rest = list
-          Pair(GBNode(k, v, empty, empty), rest)
-        } else
-          Pair(empty, list)
+        Pair(empty, list)
     }
     bal(list, s)._1
   }
diff --git a/src/library/scala/collection/mutable/ArrayBuffer.scala b/src/library/scala/collection/mutable/ArrayBuffer.scala
index 97bfe642a4..8dacd17489 100644
--- a/src/library/scala/collection/mutable/ArrayBuffer.scala
+++ b/src/library/scala/collection/mutable/ArrayBuffer.scala
@@ -14,7 +14,7 @@ package scala.collection.mutable
 
 import Predef._
 
-/** An implementation of the Buffer class using an array to
+/** An implementation of the <code>Buffer</code> class using an array to
  *  represent the assembled sequence internally.
  *
  *  @author  Matthias Zenger
@@ -23,7 +23,7 @@ import Predef._
 [serializable]
 class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
 
-  /** Append a single element to this buffer and return
+  /** Appends a single element to this buffer and returns
    *  the identity of the buffer.
    *
    *  @param elem  the element to append.
@@ -39,13 +39,17 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
    *  buffer is returned.
    *
    *  @param iter  the iterable object.
+   *  @return      the updated buffer.
    */
-  override def ++(iter: Iterable[A]): Buffer[A] = { insertAll(size, iter); this }
+  override def ++(iter: Iterable[A]): Buffer[A] = {
+    insertAll(size, iter); this
+  }
 
-  /** Prepend a single element to this buffer and return
+  /** Prepends a single element to this buffer and return
    *  the identity of the buffer.
    *
    *  @param elem  the element to append.
+   *  @return      the updated buffer.
    */
   def +:(elem: A): Buffer[A] = {
     ensureSize(size+1)
@@ -55,8 +59,11 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
     this
   }
 
-  /** returns the i-th element of this ArrayBuffer. Throws IndexOutOfBoundException if
-   *  i is out of bounds.
+  /** Returns the i-th element of this ArrayBuffer.
+   *
+   *  @param i  the specified index.
+   *  @return   the i-th element.
+   *  @throws IndexOutOfBoundException if <code>i</code> is out of bounds.
    */
   override def apply(i: Int) = {
     if ((i < 0) || (i >= size))
@@ -70,6 +77,7 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
    *  buffer is returned.
    *
    *  @param iter  the iterable object.
+   *  @return      the updated buffer.
    */
   override def ++:(iter: Iterable[A]): Buffer[A] = { insertAll(0, iter); this }
 
@@ -79,16 +87,17 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
    *
    *  @param n     the index where a new element will be inserted.
    *  @param iter  the iterable object providing all elements to insert.
+   *  @throws IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   def insertAll(n: Int, iter: Iterable[A]): Unit = {
     if ((n < 0) || (n > size))
       throw new IndexOutOfBoundsException("cannot insert element at " + n);
-    val xs = iter.elements.toList;
-    val len = xs.length;
-    ensureSize(size+len);
-    copy(n, n + len, size - n);
-    xs.copyToArray(array, n);
-    size = size + len;
+    val xs = iter.elements.toList
+    val len = xs.length
+    ensureSize(size+len)
+    copy(n, n + len, size - n)
+    xs.copyToArray(array, n)
+    size = size + len
   }
 
   /** Replace element at index <code>n</code> with the new element
@@ -96,6 +105,7 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
    *
    *  @param n       the index of the element to replace.
    *  @param newelem the new element.
+   *  @throws IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   def update(n: Int, newelem: A): Unit = {
     if ((n < 0) || (n >= size))
@@ -110,6 +120,8 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
   /** Removes the element on a given index position.
    *
    *  @param n  the index which refers to the element to delete.
+   *  @return   the updated array buffer.
+   *  @throws IndexOutOfBoundsException if <code>n</code> is out of bounds.
    */
   def remove(n: Int): A = {
     if ((n < 0) || (n >= size))
@@ -123,7 +135,7 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
   /** Clears the buffer contents.
    */
   def clear: Unit = {
-    size = 0;
+    size = 0
   }
 
   /** Return a clone of this buffer.
@@ -131,8 +143,8 @@ class ArrayBuffer[A] extends Buffer[A] with ResizableArray[A] {
    *  @return an <code>ArrayBuffer</code> with the same elements.
    */
   override def clone(): Buffer[A] = {
-    val res = new ArrayBuffer[A];
-    res ++= this;
+    val res = new ArrayBuffer[A]
+    res ++= this
     res
   }
 
diff --git a/src/library/scala/collection/mutable/BufferProxy.scala b/src/library/scala/collection/mutable/BufferProxy.scala
index 86b80613fd..c43b34ef2b 100644
--- a/src/library/scala/collection/mutable/BufferProxy.scala
+++ b/src/library/scala/collection/mutable/BufferProxy.scala
@@ -12,7 +12,8 @@
 package scala.collection.mutable
 
 
-/** This is a simple proxy class for <code>scala.collection.mutable.Buffer</code>.
+/** This is a simple proxy class for <a href="Buffer.html"
+ *  target="contentFrame"><code>scala.collection.mutable.Buffer</code></a>.
  *  It is most useful for assembling customized set abstractions
  *  dynamically using object composition and forwarding.
  *
diff --git a/src/library/scala/collection/mutable/History.scala b/src/library/scala/collection/mutable/History.scala
index 85b081e0ea..676d798961 100644
--- a/src/library/scala/collection/mutable/History.scala
+++ b/src/library/scala/collection/mutable/History.scala
@@ -27,6 +27,10 @@ class History[A, B] extends AnyRef with Subscriber[A, B] with Iterable[Pair[B, A
 
   val maxHistory: Int = 1000
 
+  /**
+   *  @param pub   ...
+   *  @param event ...
+   */
   def notify(pub: B, event: A): Unit = {
     if (log.length >= maxHistory) {
       val old = log.dequeue;
diff --git a/src/library/scala/collection/mutable/MapProxy.scala b/src/library/scala/collection/mutable/MapProxy.scala
index 872ae4a48d..20c326b968 100644
--- a/src/library/scala/collection/mutable/MapProxy.scala
+++ b/src/library/scala/collection/mutable/MapProxy.scala
@@ -12,9 +12,14 @@
 package scala.collection.mutable
 
 
-/** This is a simple wrapper class for <code>scala.collection.mutable.Map</code>.
- *  It is most useful for assembling customized map abstractions
- *  dynamically using object composition and forwarding.
+/** <p>
+ *    This is a simple wrapper class for <a href="Map.html"
+ *    target="contentFrame"><code>scala.collection.mutable.Map</code></a>.
+ *  </p>
+ *  <p>
+ *    It is most useful for assembling customized map abstractions
+ *    dynamically using object composition and forwarding.
+ *  </p>
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 21/07/2003
diff --git a/src/library/scala/collection/mutable/Set.scala b/src/library/scala/collection/mutable/Set.scala
index b64cd35db0..ec8dfd2fd2 100644
--- a/src/library/scala/collection/mutable/Set.scala
+++ b/src/library/scala/collection/mutable/Set.scala
@@ -13,7 +13,8 @@ package scala.collection.mutable
 
 /** This class represents mutable sets. Concrete set implementations
  *  just have to provide functionality for the abstract methods in
- *  <code>scala.collection.Set</code> as well as for <code>add</code>,
+ *  <a href="../Set.html" target="contentFrame">
+ *  <code>scala.collection.Set</code></a> as well as for <code>add</code>,
  *  <code>remove</code>, and <code>clear</code>.
  *
  *  @author  Matthias Zenger
@@ -46,7 +47,7 @@ trait Set[A] extends AnyRef with collection.Set[A]
    *
    *  @param that ...
    */
-  def ++=(that: Iterable[A]): Unit = ++=(that.elements);
+  def ++=(that: Iterable[A]): Unit = ++=(that.elements)
 
   /** This method will add all the elements provided by an iterator
    *  of the iterable object <code>that</code> to the set.
@@ -103,6 +104,7 @@ trait Set[A] extends AnyRef with collection.Set[A]
   /** Send a message to this scriptable object.
    *
    *  @param cmd  the message to send.
+   *  @throws UnsupportedOperationException if the message was not understood.
    */
   def <<(cmd: Message[A]): Unit = cmd match {
     case Include(elem) => this += elem
@@ -118,10 +120,11 @@ trait Set[A] extends AnyRef with collection.Set[A]
    */
   override def clone(): Set[A] = super.clone().asInstanceOf[Set[A]]
 
-  /** The hashCode method always yields an error, since it is not
-   *  safe to use mutable stacks as keys in hash tables.
+  /** The <code>hashCode</code> method always yields an error, since it is
+   *  not safe to use mutable stacks as keys in hash tables.
    *
    *  @return never.
    */
-  override def hashCode(): Int = throw new UnsupportedOperationException("unsuitable as hash key")
+  override def hashCode(): Int =
+    throw new UnsupportedOperationException("unsuitable as hash key")
 }
diff --git a/src/library/scala/collection/mutable/SetProxy.scala b/src/library/scala/collection/mutable/SetProxy.scala
index 8356b4b0ba..54c0c753b5 100644
--- a/src/library/scala/collection/mutable/SetProxy.scala
+++ b/src/library/scala/collection/mutable/SetProxy.scala
@@ -12,7 +12,8 @@
 package scala.collection.mutable
 
 
-/** This is a simple wrapper class for <code>scala.collection.mutable.Set</code>.
+/** This is a simple wrapper class for <a href="Set.html"
+ *  target="contentFrame"><code>scala.collection.mutable.Set</code></a>.
  *  It is most useful for assembling customized set abstractions
  *  dynamically using object composition and forwarding.
  *
diff --git a/src/library/scala/collection/mutable/Subscriber.scala b/src/library/scala/collection/mutable/Subscriber.scala
index 330a5a2c22..b6c33a8b1b 100644
--- a/src/library/scala/collection/mutable/Subscriber.scala
+++ b/src/library/scala/collection/mutable/Subscriber.scala
@@ -14,11 +14,12 @@ package scala.collection.mutable
 
 /** <code>Subscriber[A, B]</code> objects may subscribe to events of
  *  type <code>A</code> published by an object of type <code>B</code>.
- *  <code>B</code> is typically a subtype of <code>Publisher</code>.
+ *  <code>B</code> is typically a subtype of <a href="Publisher.html"
+ *  target="contentFrame"><code>Publisher</code></a>.
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 08/07/2003
  */
 trait Subscriber[-A, -B] {
-    def notify(pub: B, event: A): Unit
+  def notify(pub: B, event: A): Unit
 }
diff --git a/src/library/scala/io/Source.scala b/src/library/scala/io/Source.scala
index 4087ded64e..a384af99df 100644
--- a/src/library/scala/io/Source.scala
+++ b/src/library/scala/io/Source.scala
@@ -23,10 +23,11 @@ import compat.StringBuilder
  */
 object Source {
 
-  /** Creates Source from array of bytes, with empty description.
+  /** Creates a <code>Source</code> instance from the given array of bytes,
+   *  with empty description.
    *
    *  @param bytes ...
-   *  @return      ...
+   *  @return      the created <code>Source</code> instance.
    */
   def fromBytes(bytes: Array[Byte]): Source =
     fromString(new String(bytes))
@@ -41,10 +42,10 @@ object Source {
   def fromBytes(bytes: Array[Byte], enc: String): Source =
     fromString(new String(bytes, enc))
 
-  /** Creates Source from a single character.
+  /** Creates a <code>Source</code> instance from a single character.
    *
    *  @param c ...
-   *  @return  ...
+   *  @return  the create <code>Source</code> instance.
    */
   def fromChar(c: Char): Source = {
     val it = Iterator.single(c)
@@ -134,9 +135,17 @@ object Source {
     s
   }
 
-  def fromURL(s:String): Source =
+  /**
+   *  @param s    ...
+   *  @return     ...
+   */
+  def fromURL(s: String): Source =
     fromURL(new java.net.URL(s))
 
+  /**
+   *  @param url  ...
+   *  @return     ...
+   */
   def fromURL(url: java.net.URL): Source = {
     val it = new Iterator[Char] {
       var data: Int = _
@@ -156,8 +165,9 @@ object Source {
 
 }
 
-/** an iterable representation of source files.
- *  calling method reset returns an identical, resetted source
+/** The class <code>Source</code> implements an iterable representation
+ *  of source files. Calling method <code>reset</code> returns an identical,
+ *  resetted source.
  *
  *  @author  Burak Emir
  *  @version 1.0
@@ -197,18 +207,22 @@ abstract class Source extends Iterator[Char] {
   //
 
   /** convenience method, returns given line (not including newline)
-   *  from Source
+   *  from Source.
+   *
+   *  @param line the line index.
+   *  @return     the character string of the specified line.
+   *  @throws IllegalArgumentException
    */
   def getLine(line: Int): String = {
     val buf = new StringBuffer()
     val it = reset
     var i = 0
 
-    while( it.hasNext && i < (line-1))
-      if('\n' == it.next)
+    while (it.hasNext && i < (line-1))
+      if ('\n' == it.next)
         i = i + 1;
 
-    if(!it.hasNext) // this should not happen
+    if (!it.hasNext) // this should not happen
       throw new java.lang.IllegalArgumentException(
         "line "+line+" does not exist?!"
       );
@@ -222,7 +236,7 @@ abstract class Source extends Iterator[Char] {
     buf.setLength(0)
     res
   }
-  /** returns true if this source has more characters
+  /** Returns <code>true</code> if this source has more characters.
    */
   def hasNext = iter.hasNext
 
@@ -271,7 +285,7 @@ abstract class Source extends Iterator[Char] {
     val buf = new StringBuffer
     val line = Position.line(pos)
     val col = Position.column(pos)
-    buf.append(descr + ":"+line+":"+col+": "+msg)
+    buf.append(descr + ":" + line + ":" + col + ": " + msg)
     buf.append(getLine(line))
     var i = 1
     while (i < col) {
diff --git a/src/library/scala/runtime/RichString.scala b/src/library/scala/runtime/RichString.scala
index d6195e034b..97836fc54b 100755
--- a/src/library/scala/runtime/RichString.scala
+++ b/src/library/scala/runtime/RichString.scala
@@ -21,16 +21,25 @@ final class RichString(s: String) {
 
   private def isLineBreak(c: Char) = c == LF || c == FF
 
-  /** Treat string as a function that maps indices to characters
+  /** Treat string as a function that maps indices to characters.
+   *
+   *  @param index ...
+   *  @return      the character at position <code>index</code>.
    */
   def apply(index: Int): Char = s charAt index
 
-  /** Strip trailing line end character from this string if it has one.
-   *  A line end character is one of
-   *   LF - line feed   (0x0A hex)
-   *   FF - form feed   (0x0C hex)
-   *  If a line feed character LF is preceded by a carriage return CR (0x0D hex),
-   *  the CR character is also stripped (Windows convention)
+  /** <p>
+   *    Strip trailing line end character from this string if it has one.
+   *    A line end character is one of
+   *  </p>
+   *  <ul style="list-style-type: none;">
+   *    <li>LF - line feed   (0x0A hex)</li>
+   *    <li>FF - form feed   (0x0C hex)</li>
+   *  </ul>
+   *  <p>
+   *    If a line feed character LF is preceded by a carriage return CR
+   *    (0x0D hex), the CR character is also stripped (Windows convention).
+   *  </p>
    */
   def stripLineEnd: String = {
     val len = s.length
@@ -44,12 +53,19 @@ final class RichString(s: String) {
     }
   }
 
-  /** Return all lines in this string in an iterator, including trailing line end characters
-   *  The number of strings returned is one greater than the number of line end characters
-   *  in this string. For an empty string, a single empty line is returned.
-   *  A line end character is one of
-   *   LF - line feed   (0x0A hex)
-   *   FF - form feed   (0x0C hex)
+  /** <p>
+   *    Return all lines in this string in an iterator, including trailing
+   *    line end characters.
+   *  </p>
+   *  <p>
+   *    The number of strings returned is one greater than the number of line
+   *    end characters in this string. For an empty string, a single empty
+   *    line is returned. A line end character is one of
+   *  </p>
+   *  <ul style="list-style-type: none;">
+   *    <li>LF - line feed   (0x0A hex)</li>
+   *    <li>FF - form feed   (0x0C hex)</li>
+   *  </ul>
    */
   def linesWithSeparators = new Iterator[String] {
     val len = s.length
@@ -64,14 +80,19 @@ final class RichString(s: String) {
     }
   }
 
-  /** Return all lines in this string in an iterator, excluding trailing line end characters
-   *  I.e. apply `.stripLineEnd' to all lines returned by `linesWithSeparators'
+  /** Return all lines in this string in an iterator, excluding trailing line
+   *  end characters, i.e. apply <code>.stripLineEnd</code> to all lines
+   *  returned by <code>linesWithSeparators</code>.
    */
   def lines = linesWithSeparators map (line => new RichString(line).stripLineEnd)
 
-  /** For every line in this string:
-   *     Strip a leading prefix consisting of blanks or control characters followed by
-   *     `marginChar' from the line.
+  /** <p>
+   *    For every line in this string:
+   *  </p>
+   *  <blockquote>
+   *     Strip a leading prefix consisting of blanks or control characters
+   *     followed by <code>marginChar</code> from the line.
+   *  </blockquote>
    */
   def stripMargin(marginChar: Char): String = {
     val buf = new scala.compat.StringBuilder()
@@ -85,9 +106,13 @@ final class RichString(s: String) {
     buf.toString
   }
 
-  /** For every line in this string:
-   *     Strip a leading prefix consisting of blanks or control characters followed by
-   *     `|' from the line.
+  /** <p>
+   *    For every line in this string:
+   *  </p>
+   *  <blockquote>
+   *     Strip a leading prefix consisting of blanks or control characters
+   *     followed by <code>|</code> from the line.
+   *  </blockquote>
    */
   def stripMargin: String = stripMargin('|')
 }
diff --git a/src/library/scala/util/logging/Logged.scala b/src/library/scala/util/logging/Logged.scala
index 6d9e423a02..5c8aa2808a 100644
--- a/src/library/scala/util/logging/Logged.scala
+++ b/src/library/scala/util/logging/Logged.scala
@@ -11,22 +11,27 @@
 
 package scala.util.logging
 
-/**
- *  Mixing in the class Logged indicates that a class provides support
- *  for logging. For instance, a developer of a library writes
- *  <code>
-   class MyClass with Logged { ... do stuff, call log }
-   </code>
-   *
-   * The user of the library instantiates:
-   <code>
-   val x = new MyClass() with ConsoleLogger;
-   </code>
-   * and the logging will be sent to the Console.
-   */
+/** <p>
+ *    Mixing in the class <code>Logged</code> indicates that a class provides
+ *    support for logging. For instance, the developer of a library writes
+ *  </p>
+ *  <pre>
+ *    <b>class</b> MyClass <b>with</b> Logged { /* do stuff, call log */ }
+ *  </pre>
+ *  <p>
+ *    The user of the library instantiates:
+ *  </p>
+ *  <pre>
+ *    <b>val</b> x = <b>new</b> MyClass() <b>with</b> ConsoleLogger
+ *  </pre>
+ *  <p>
+ *    and the logging will be sent to the <a href="../../Console$object.html"
+ *    target="contentFrame"><code>Console</code></a> object.
+ *  </p>
+ */
 trait Logged {
 
-  /** this method should log the message given as argument somewhere
+  /** This method should log the message given as argument somewhere
    *  as a side-effect.
    *
    *  @param msg ...
diff --git a/src/library/scala/xml/NodeSeq.scala b/src/library/scala/xml/NodeSeq.scala
index 946951fa75..ff8c1e7ff3 100644
--- a/src/library/scala/xml/NodeSeq.scala
+++ b/src/library/scala/xml/NodeSeq.scala
@@ -25,8 +25,8 @@ object NodeSeq {
   implicit def view(s: Seq[Node]): NodeSeq = fromSeq(s)
 }
 
-/** This class implements a wrapper around Seq[Node] that adds XPath and
- *  comprehension methods.
+/** This class implements a wrapper around <code>Seq[Node]</code> that
+ *  adds XPath and comprehension methods.
  *
  *  @author  Burak Emir
  *  @version 1.0
@@ -43,14 +43,15 @@ abstract class NodeSeq extends Seq[Node] {
   /** structural equality */
   override def equals(x: Any) = x match {
     case z:Node      => (length == 1) && z == apply(0)
-    case z:Seq[Node] => sameElements( z )
+    case z:Seq[Node] => sameElements(z)
     case z:String    => text == z
     case _           => false;
   }
 
-  /** projection function. Similar to XPath, use this \ "foo" to get a list
-   *  of all elements of this sequence that are labelled with "foo".
-   *  Use \ "_" as a wildcard. The document order is preserved.
+  /** Projection function. Similar to XPath, use <code>this \ "foo"</code>
+   *  to get a list of all elements of this sequence that are labelled with
+   *  <code>"foo"</code>. Use <code>\ "_"</code> as a wildcard.
+   *  The document order is preserved.
    *
    *  @param that ...
    *  @return     ...
@@ -93,9 +94,10 @@ abstract class NodeSeq extends Seq[Node] {
       NodeSeq.fromSeq(zs.reverse)
   }
 
-  /** projection function. Similar to XPath, use this \\ 'foo to get a list
-   *  of all elements of this sequence that are labelled with "foo".
-   *  Use \\ "_" as a wildcard. The document order is preserved.
+  /** projection function. Similar to XPath, use <code>this \\ 'foo</code>
+   *  to get a list of all elements of this sequence that are labelled with
+   *  <code>"foo"</code>. Use <code>\\ "_"</code> as a wildcard.
+   *  The document order is preserved.
    *
    *  @param that ...
    *  @return     ...