Revamped scala-doc.

10 files changed, 84 insertions, 53 deletions

diff --git a/src/library/scala/Iterable.scala b/src/library/scala/Iterable.scala
index 579e249c3f..85d61c7227 100644
--- a/src/library/scala/Iterable.scala
+++ b/src/library/scala/Iterable.scala
@@ -382,4 +382,22 @@ trait Iterable[+A] {
     }
     buf.append(end)
   }
+
+  /** Fills the given array <code>xs</code> with the elements of
+   *  this sequence starting at position <code>start</code>.
+   *
+   *  @param  xs the array to fill.
+   *  @param  start starting index.
+   *  @pre    the array must be large enough to hold all elements.
+   */
+  def copyToArray[B >: A](xs: Array[B], start: Int): Unit =
+    elements.copyToArray(xs, start)
+
+  /** Converts this iterable to a fresh Array with elements.
+   */
+  def toArray[B >: A]: Array[B] = toList.toArray
+
+  /** Is this collection empty? */
+  def isEmpty = elements.hasNext
+
 }
diff --git a/src/library/scala/List.scala b/src/library/scala/List.scala
index b6723b5517..de0b24c716 100644
--- a/src/library/scala/List.scala
+++ b/src/library/scala/List.scala
@@ -401,26 +401,23 @@ sealed abstract class List[+a] extends Seq[a] {
 
   /** <p>
    *    Add an element <code>x</code> at the beginning of this list.
-   *    Example:
    *  </p>
-   *  <pre>
-   *    1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)</pre>
    *
    *  @param x the element to append.
    *  @return  the list with <code>x</code> appended at the beginning.
+   *  @ex <code>1 :: List(2, 3) = List(2, 3).::(1) = List(1, 2, 3)</code>
    */
   def ::[b >: a] (x: b): List[b] =
     new scala.::(x, this)
 
   /** <p>
    *    Returns a list resulting from the concatenation of the given
-   *    list <code>prefix</code> and this list. Example:
+   *    list <code>prefix</code> and this list.
    *  </p>
-   *  <pre>
-   *    List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)</pre>
    *
    *  @param prefix the list to concatenate at the beginning of this list.
    *  @return the concatenation of the two lists.
+   *  @ex <code>List(1, 2) ::: List(3, 4) = List(3, 4).:::(List(1, 2)) = List(1, 2, 3, 4)</code>
    */
   def :::[b >: a](prefix: List[b]): List[b] =
     if (isEmpty) prefix
@@ -767,20 +764,18 @@ sealed abstract class List[+a] extends Seq[a] {
    *    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("Steve", "Tom", "John", "Bob")
-   *      .sort((e1, e2) => (e1 compareTo e2) &lt; 0) =
-   *    List("Bob", "John", "Steve", "Tom")</pre>
-   *  <p>
-   *    Note: The current implementation is inefficent for
-   *    already sorted lists.
+   *    <code>e2</code>.
    *  </p>
    *
    *  @param lt the comparison function
    *  @return   a list sorted according to the comparison function
    *            <code>&lt;(e1: a, e2: a) =&gt; Boolean</code>.
+   *  @ex <pre>
+   *    List("Steve", "Tom", "John", "Bob")
+   *      .sort((e1, e2) => (e1 compareTo e2) &lt; 0) =
+   *    List("Bob", "John", "Steve", "Tom")</pre>
+   *  @note The current implementation is inefficent for
+   *    already sorted lists.
    */
   def sort(lt : (a,a) => Boolean): List[a] = {
     def sort_1(smaller: List[a], acc: List[a]): List[a] =
diff --git a/src/library/scala/PartialFunction.scala b/src/library/scala/PartialFunction.scala
index 06b9f70681..13f4602c5f 100644
--- a/src/library/scala/PartialFunction.scala
+++ b/src/library/scala/PartialFunction.scala
@@ -29,7 +29,8 @@ trait PartialFunction[-A, +B] extends AnyRef with (A => B) {
    */
   def isDefinedAt(x: A): Boolean;
 
-  def orElse[A1 <: A, B1 >: B](that: PartialFunction[A1, B1]) = new PartialFunction[A1, B1] {
+  def orElse[A1 <: A, B1 >: B](that: PartialFunction[A1, B1]) : PartialFunction[A1, B1] =
+    new PartialFunction[A1, B1] {
     def isDefinedAt(x: A1): Boolean =
       PartialFunction.this.isDefinedAt(x) || that.isDefinedAt(x)
     def apply(x: A1): B1 =
@@ -37,7 +38,7 @@ trait PartialFunction[-A, +B] extends AnyRef with (A => B) {
       else that.apply(x)
   }
 
-  override def andThen[C](k: B => C) = new PartialFunction[A, C] {
+  override def andThen[C](k: B => C) : PartialFunction[A, C] = new PartialFunction[A, C] {
     def isDefinedAt(x: A): Boolean = PartialFunction.this.isDefinedAt(x)
     def apply(x: A): C = k(PartialFunction.this.apply(x))
   }
diff --git a/src/library/scala/Seq.scala b/src/library/scala/Seq.scala
index e1d5581ea1..78dc4af435 100644
--- a/src/library/scala/Seq.scala
+++ b/src/library/scala/Seq.scala
@@ -79,7 +79,7 @@ trait Seq[+A] extends AnyRef with PartialFunction[Int, A] with Iterable[A] {
 
   /** Returns true if length == 0
    */
-  def isEmpty: Boolean = { length == 0 }
+  override def isEmpty: Boolean = { length == 0 }
 
   /** Appends two iterable objects.
    *
@@ -242,25 +242,6 @@ trait Seq[+A] extends AnyRef with PartialFunction[Int, A] with Iterable[A] {
   @deprecated
   def subseq(from: Int, end: Int): Seq[A] = slice(from, end - from)
 
-
-  /** Converts this sequence to a fresh Array with <code>length</code>
-   * elements.
-   */
-  def toArray[B >: A]: Array[B] = {
-    val result = new Array[B](length)
-    copyToArray(result, 0)
-    result
-  }
-
-  /** Fills the given array <code>xs</code> with the elements of
-   *  this sequence starting at position <code>start</code>.
-   *
-   *  @param  xs the array to fill.
-   *  @param  start starting index.
-   *  @pre    the array must be large enough to hold all elements.
-   */
-  def copyToArray[B >: A](xs: Array[B], start: Int): Unit = elements.copyToArray(xs, start)
-
   /** Customizes the <code>toString</code> method.
    *
    *  @return a string representation of this sequence.
@@ -272,5 +253,15 @@ trait Seq[+A] extends AnyRef with PartialFunction[Int, A] with Iterable[A] {
   /** Defines the prefix of the string representation.
    */
   protected def stringPrefix: String = "Seq"
+
+  /** Converts this sequence to a fresh Array with <code>length</code> elements.
+   */
+  override def toArray[B >: A]: Array[B] = {
+    val result = new Array[B](length)
+    copyToArray(result, 0)
+    result
+  }
+
+
 }
 
diff --git a/src/library/scala/Symbol.scala b/src/library/scala/Symbol.scala
index 9bc195dce6..e1edf78686 100644
--- a/src/library/scala/Symbol.scala
+++ b/src/library/scala/Symbol.scala
@@ -11,9 +11,9 @@
 
 package scala
 
-import collection.jcl.WeakHashMap
+import scala.collection.jcl
 
-private[scala] object internedSymbols extends WeakHashMap[String, Symbol]
+private[scala] object internedSymbols extends jcl.HashMap[String, ref.WeakReference[Symbol]]
 
 /** <p>
  *    Instances of <code>Symbol</code> can be created easily with
@@ -47,11 +47,9 @@ final case class Symbol(name: String) {
    *
    *  @return the unique reference to this symbol.
    */
-  def intern: Symbol = internedSymbols get name match {
-    case Some(sym) =>
-      sym
+  def intern: Symbol = synchronized { internedSymbols get name match {
+    case Some(sym) if sym.isValid => sym.apply
     case None =>
-      internedSymbols(name) = this
-      this
-  }
+      internedSymbols(name) = new ref.WeakReference(this); this
+  } }
 }
diff --git a/src/library/scala/collection/Map.scala b/src/library/scala/collection/Map.scala
index f3aab7c16a..df2f2630d3 100644
--- a/src/library/scala/collection/Map.scala
+++ b/src/library/scala/collection/Map.scala
@@ -63,7 +63,7 @@ trait Map[A, +B] extends PartialFunction[A, B] with Iterable[(A, B)] {
    *
    *  @return <code>true</code> iff the map is empty.
    */
-  def isEmpty: Boolean = size == 0
+  override def isEmpty: Boolean = size == 0
 
   /** Retrieve the value which is associated with the given key. This
    *  method throws an exception if there is no mapping from the given
diff --git a/src/library/scala/collection/Set.scala b/src/library/scala/collection/Set.scala
index fcea89893e..6f90a27cb4 100644
--- a/src/library/scala/collection/Set.scala
+++ b/src/library/scala/collection/Set.scala
@@ -61,7 +61,7 @@ trait Set[A] extends (A => Boolean) with Iterable[A] {
    *
    *  @return <code>true</code> iff there is no element in the set.
    */
-  def isEmpty: Boolean = size == 0
+  override def isEmpty: Boolean = size == 0
 
   /** Checks if this set is a subset of set <code>that</code>.
    *
@@ -89,7 +89,7 @@ trait Set[A] extends (A => Boolean) with Iterable[A] {
 
   /** hashcode for this set */
   override def hashCode() =
-    (0 /: this)((hash, e) => hash * 41 + e.hashCode())
+    (0 /: this)((hash, e) => hash + e.hashCode())
 
 
   /** Returns a string representation of this set.
@@ -97,4 +97,9 @@ trait Set[A] extends (A => Boolean) with Iterable[A] {
    *  @return a string showing all elements of this set.
    */
   override def toString() = mkString("Set(", ", ", ")")
+  override def toArray[B >: A]: Array[B] = {
+    val result = new Array[B](size)
+    copyToArray(result, 0)
+    result
+  }
 }
diff --git a/src/library/scala/collection/Sorted.scala b/src/library/scala/collection/Sorted.scala
index 5040246a91..eda7c21aef 100644
--- a/src/library/scala/collection/Sorted.scala
+++ b/src/library/scala/collection/Sorted.scala
@@ -33,8 +33,8 @@ trait Sorted[K,+A] extends Ranged[K,A] {
   override def range(from: K, until: K) = rangeImpl(Some(from),Some(until));
 
   /** Create a range projection of this collection with no lower-bound.
-   ** @param to The upper-bound (inclusive) of the ranged projection.
-   **/
+   *  @param to The upper-bound (inclusive) of the ranged projection.
+   */
   def to(to : K): Sorted[K,A] = {
     // tough!
     val i = keySet.from(to).elements;
diff --git a/src/library/scala/collection/jcl/MutableIterable.scala b/src/library/scala/collection/jcl/MutableIterable.scala
index 75f6b01717..081865169a 100644
--- a/src/library/scala/collection/jcl/MutableIterable.scala
+++ b/src/library/scala/collection/jcl/MutableIterable.scala
@@ -45,9 +45,7 @@ trait MutableIterable[A] extends Iterable[A] {
   /** retain only elements that are also in that.
    **/
   def retainAll(that : Iterable[A]) : Boolean = elements.retain(s => that.exists(t => t == s));
-  /** @return true if the element has no elements.
-   **/
-  def isEmpty : Boolean = !elements.hasNext;
+
   /** @return the current number of elements in the collection.
    **/
   def size : Int = {
diff --git a/src/library/scala/collection/mutable/Set.scala b/src/library/scala/collection/mutable/Set.scala
index a516fef5f2..8e081191b6 100644
--- a/src/library/scala/collection/mutable/Set.scala
+++ b/src/library/scala/collection/mutable/Set.scala
@@ -202,4 +202,29 @@ trait Set[A] extends collection.Set[A] with Scriptable[Message[A]] {
    *  @return  a set with the same elements.
    */
   override def clone(): Set[A] = super.clone().asInstanceOf[Set[A]]
+
+  /** Return a read-only projection of this set */
+  def readOnly : scala.collection.Set[A] = new scala.collection.Set[A] {
+    /** used to trigger version checking in JCL and hopefully the mutable collections */
+    override val hashCode = Set.this.hashCode
+    private def check =
+      if (false && hashCode != Set.this.hashCode)
+        throw new java.util.ConcurrentModificationException
+
+    def contains(item : A) = {
+      check
+      Set.this.contains(item)
+    }
+    override def toString = {
+      "read-only-" + Set.this.toString
+    }
+    override def size = {
+      check
+      Set.this.size
+    }
+    override def elements = {
+      check
+      Set.this.elements
+    }
+  }
 }