Merge branch 'master' into issue/5374

15 files changed, 210 insertions, 119 deletions

diff --git a/src/library/scala/collection/SeqLike.scala b/src/library/scala/collection/SeqLike.scala
index 6d84b4276b..02298ef096 100644
--- a/src/library/scala/collection/SeqLike.scala
+++ b/src/library/scala/collection/SeqLike.scala
@@ -151,8 +151,9 @@ trait SeqLike[+A, +Repr] extends IterableLike[A, Repr] with GenSeqLike[A, Repr]
     def next(): Repr = {
       if (!hasNext)
         Iterator.empty.next
-
-      val result = (self.newBuilder ++= elms.toList).result
+      
+      val forcedElms = new mutable.ArrayBuffer[A](elms.size) ++= elms
+      val result = (self.newBuilder ++= forcedElms).result
       var i = idxs.length - 2
       while(i >= 0 && idxs(i) >= idxs(i+1))
         i -= 1
diff --git a/src/library/scala/collection/immutable/HashMap.scala b/src/library/scala/collection/immutable/HashMap.scala
index 55ce8fa822..9cde20f1df 100644
--- a/src/library/scala/collection/immutable/HashMap.scala
+++ b/src/library/scala/collection/immutable/HashMap.scala
@@ -111,7 +111,7 @@ object HashMap extends ImmutableMapFactory[HashMap] with BitOperations.Int {
 
   // TODO: add HashMap2, HashMap3, ...
 
-  class HashMap1[A,+B](private[HashMap] var key: A, private[HashMap] var hash: Int, private[collection] var value: (B @uV), private[collection] var kv: (A,B @uV)) extends HashMap[A,B] {
+  class HashMap1[A,+B](private[collection] val key: A, private[collection] val hash: Int, private[collection] val value: (B @uV), private[collection] var kv: (A,B @uV)) extends HashMap[A,B] {
     override def size = 1
 
     private[collection] def getKey = key
@@ -176,13 +176,14 @@ object HashMap extends ImmutableMapFactory[HashMap] with BitOperations.Int {
 
     override def iterator: Iterator[(A,B)] = Iterator(ensurePair)
     override def foreach[U](f: ((A, B)) => U): Unit = f(ensurePair)
+    // this method may be called multiple times in a multithreaded environment, but that's ok
     private[HashMap] def ensurePair: (A,B) = if (kv ne null) kv else { kv = (key, value); kv }
     protected override def merge0[B1 >: B](that: HashMap[A, B1], level: Int, merger: Merger[B1]): HashMap[A, B1] = {
       that.updated0(key, hash, level, value, kv, merger)
     }
   }
 
-  private[collection] class HashMapCollision1[A, +B](private[HashMap] var hash: Int, var kvs: ListMap[A, B @uV])
+  private[collection] class HashMapCollision1[A, +B](private[collection] val hash: Int, val kvs: ListMap[A, B @uV])
           extends HashMap[A, B @uV] {
 
     override def size = kvs.size
@@ -227,9 +228,9 @@ object HashMap extends ImmutableMapFactory[HashMap] with BitOperations.Int {
   }
 
   class HashTrieMap[A, +B](
-    private[HashMap] var bitmap: Int,
-    private[collection] var elems: Array[HashMap[A, B @uV]],
-    private[HashMap] var size0: Int
+    private[collection] val bitmap: Int,
+    private[collection] val elems: Array[HashMap[A, B @uV]],
+    private[collection] val size0: Int
   ) extends HashMap[A, B @uV] {
 
 /*
diff --git a/src/library/scala/collection/immutable/HashSet.scala b/src/library/scala/collection/immutable/HashSet.scala
index 8cb19d4f31..79d2fb71cc 100644
--- a/src/library/scala/collection/immutable/HashSet.scala
+++ b/src/library/scala/collection/immutable/HashSet.scala
@@ -105,7 +105,7 @@ object HashSet extends ImmutableSetFactory[HashSet] {
 
   // TODO: add HashSet2, HashSet3, ...
 
-  class HashSet1[A](private[HashSet] var key: A, private[HashSet] var hash: Int) extends HashSet[A] {
+  class HashSet1[A](private[HashSet] val key: A, private[HashSet] val hash: Int) extends HashSet[A] {
     override def size = 1
 
     override def get0(key: A, hash: Int, level: Int): Boolean =
@@ -131,7 +131,7 @@ object HashSet extends ImmutableSetFactory[HashSet] {
     override def foreach[U](f: A => U): Unit = f(key)
   }
 
-  private[immutable] class HashSetCollision1[A](private[HashSet] var hash: Int, var ks: ListSet[A])
+  private[immutable] class HashSetCollision1[A](private[HashSet] val hash: Int, val ks: ListSet[A])
             extends HashSet[A] {
 
     override def size = ks.size
@@ -178,7 +178,7 @@ object HashSet extends ImmutableSetFactory[HashSet] {
 
   }
 
-  class HashTrieSet[A](private var bitmap: Int, private[collection] var elems: Array[HashSet[A]], private var size0: Int)
+  class HashTrieSet[A](private val bitmap: Int, private[collection] val elems: Array[HashSet[A]], private val size0: Int)
         extends HashSet[A] {
 
     override def size = size0
diff --git a/src/library/scala/collection/immutable/Range.scala b/src/library/scala/collection/immutable/Range.scala
index c92c0268b6..7537558f0b 100644
--- a/src/library/scala/collection/immutable/Range.scala
+++ b/src/library/scala/collection/immutable/Range.scala
@@ -286,18 +286,36 @@ extends collection.AbstractSeq[Int]
 object Range {
   private[immutable] val MAX_PRINT = 512  // some arbitrary value
 
-  /** Counts in "Long arithmetic" so we can recognize overflow.
+  /** Counts the number of range elements.
+   *  @pre  step != 0
+   *  If the size of the range exceeds Int.MaxValue, the
+   *  result will be negative.
    */
-  def count(start: Int, end: Int, step: Int): Int =
-    count(start, end, step, false)
-
   def count(start: Int, end: Int, step: Int, isInclusive: Boolean): Int = {
-    // faster path for the common counting range
-    if (start >= 0 && end > start && end < scala.Int.MaxValue && step == 1)
-      (end - start) + ( if (isInclusive) 1 else 0 )
-    else
-      NumericRange.count[Long](start, end, step, isInclusive)
+    if (step == 0)
+      throw new IllegalArgumentException("step cannot be 0.")
+
+    val isEmpty = (
+      if (start == end) !isInclusive
+      else if (start < end) step < 0
+      else step > 0
+    )
+    if (isEmpty) 0
+    else {
+      // Counts with Longs so we can recognize too-large ranges.
+      val gap: Long    = end.toLong - start.toLong
+      val jumps: Long  = gap / step
+      // Whether the size of this range is one larger than the
+      // number of full-sized jumps.
+      val hasStub      = isInclusive || (gap % step != 0)
+      val result: Long = jumps + ( if (hasStub) 1 else 0 )
+    
+      if (result > scala.Int.MaxValue) -1
+      else result.toInt
+    }
   }
+  def count(start: Int, end: Int, step: Int): Int =
+    count(start, end, step, false)
 
   class Inclusive(start: Int, end: Int, step: Int) extends Range(start, end, step) {
 //    override def par = new ParRange(this)
diff --git a/src/library/scala/collection/immutable/Stream.scala b/src/library/scala/collection/immutable/Stream.scala
index e6587f9615..2eb2f8eb09 100644
--- a/src/library/scala/collection/immutable/Stream.scala
+++ b/src/library/scala/collection/immutable/Stream.scala
@@ -929,13 +929,19 @@ self =>
 /** A specialized, extra-lazy implementation of a stream iterator, so it can
  *  iterate as lazily as it traverses the tail.
  */
-final class StreamIterator[+A](self: Stream[A]) extends AbstractIterator[A] with Iterator[A] {
+final class StreamIterator[+A] private() extends AbstractIterator[A] with Iterator[A] {
+  def this(self: Stream[A]) {
+    this()
+    these = new LazyCell(self)
+  }
+
   // A call-by-need cell.
   class LazyCell(st: => Stream[A]) {
     lazy val v = st
   }
 
-  private var these = new LazyCell(self)
+  private var these: LazyCell = _
+
   def hasNext: Boolean = these.v.nonEmpty
   def next(): A =
     if (isEmpty) Iterator.empty.next
diff --git a/src/library/scala/collection/parallel/ParIterableLike.scala b/src/library/scala/collection/parallel/ParIterableLike.scala
index 90b64c17f9..390bd72ab5 100644
--- a/src/library/scala/collection/parallel/ParIterableLike.scala
+++ b/src/library/scala/collection/parallel/ParIterableLike.scala
@@ -895,7 +895,8 @@ self: ParIterableLike[T, Repr, Sequential] =>
     @volatile var result: R1 = null.asInstanceOf[R1]
     def map(r: R): R1
     def leaf(prevr: Option[R1]) = {
-      result = map(executeAndWaitResult(inner))
+      val initialResult = executeAndWaitResult(inner)
+      result = map(initialResult)
     }
     private[parallel] override def signalAbort() {
       inner.signalAbort
diff --git a/src/library/scala/collection/parallel/Tasks.scala b/src/library/scala/collection/parallel/Tasks.scala
index 873291fb2d..b705909cad 100644
--- a/src/library/scala/collection/parallel/Tasks.scala
+++ b/src/library/scala/collection/parallel/Tasks.scala
@@ -88,7 +88,7 @@ trait Tasks {
       if (this.throwable == null && that.throwable == null && (this.result == null || that.result == null)) {
         println("This: " + this + ", thr=" + this.throwable + "; merged with " + that + ", thr=" + that.throwable)
       } else if (this.throwable != null || that.throwable != null) {
-        println("merging this thr: " + this.throwable + " with " + that + ", thr=" + that.throwable)
+        println("merging this: " + this + " with thr: " + this.throwable + " with " + that + ", thr=" + that.throwable)
       }
     }
 
@@ -118,7 +118,7 @@ trait Tasks {
     /** Try to cancel the task.
      *  @return     `true` if cancellation is successful.
      */
-    def tryCancel: Boolean
+    def tryCancel(): Boolean
     /** If the task has been cancelled successfully, those syncing on it may
      *  automatically be notified, depending on the implementation. If they
      *  aren't, this release method should be called after processing the
@@ -161,32 +161,39 @@ trait AdaptiveWorkStealingTasks extends Tasks {
 
     def split: Seq[TaskImpl[R, Tp]]
 
-    def compute() = if (body.shouldSplitFurther) internal else body.tryLeaf(None)
+    def compute() = if (body.shouldSplitFurther) {
+      internal()
+      release()
+    } else {
+      body.tryLeaf(None)
+      release()
+    }
 
     def internal() = {
       var last = spawnSubtasks()
-
+      
       last.body.tryLeaf(None)
+      last.release()
       body.result = last.body.result
       body.throwable = last.body.throwable
-
+      
       while (last.next != null) {
         // val lastresult = Option(last.body.result)
         val beforelast = last
         last = last.next
-        if (last.tryCancel) {
+        if (last.tryCancel()) {
           // println("Done with " + beforelast.body + ", next direct is " + last.body)
           last.body.tryLeaf(Some(body.result))
-          last.release
+          last.release()
         } else {
           // println("Done with " + beforelast.body + ", next sync is " + last.body)
-          last.sync
+          last.sync()
         }
         // println("Merging " + body + " with " + last.body)
         body.tryMerge(last.body.repr)
       }
     }
-
+    
     def spawnSubtasks() = {
       var last: TaskImpl[R, Tp] = null
       var head: TaskImpl[R, Tp] = this
@@ -196,7 +203,7 @@ trait AdaptiveWorkStealingTasks extends Tasks {
         for (t <- subtasks.tail.reverse) {
           t.next = last
           last = t
-          t.start
+          t.start()
         }
       } while (head.body.shouldSplitFurther);
       head.next = last
@@ -230,12 +237,12 @@ trait ThreadPoolTasks extends Tasks {
     // utb: var future: Future[_] = null
     @volatile var owned = false
     @volatile var completed = false
-
+    
     def start() = synchronized {
       // debuglog("Starting " + body)
       // utb: future = executor.submit(this)
       executor.synchronized {
-        incrTasks
+        incrTasks()
         executor.submit(this)
       }
     }
@@ -249,9 +256,9 @@ trait ThreadPoolTasks extends Tasks {
           //assert(executor.getCorePoolSize == (coresize + 1))
         }
       }
-      if (!completed) this.wait
+      while (!completed) this.wait
     }
-    def tryCancel = synchronized {
+    def tryCancel() = synchronized {
       // utb: future.cancel(false)
       if (!owned) {
         // debuglog("Cancelling " + body)
@@ -259,7 +266,7 @@ trait ThreadPoolTasks extends Tasks {
         true
       } else false
     }
-    def run = {
+    def run() = {
       // utb: compute
       var isOkToRun = false
       synchronized {
@@ -270,17 +277,17 @@ trait ThreadPoolTasks extends Tasks {
       }
       if (isOkToRun) {
         // debuglog("Running body of " + body)
-        compute
-        release
+        compute()
       } else {
         // just skip
         // debuglog("skipping body of " + body)
       }
     }
-    override def release = synchronized {
+    override def release() = synchronized {
+      //println("releasing: " + this + ", body: " + this.body)
       completed = true
       executor.synchronized {
-        decrTasks
+        decrTasks()
       }
       this.notifyAll
     }
@@ -305,10 +312,10 @@ trait ThreadPoolTasks extends Tasks {
     val t = newTaskImpl(task)
 
     // debuglog("-----------> Executing without wait: " + task)
-    t.start
+    t.start()
 
     () => {
-      t.sync
+      t.sync()
       t.body.forwardThrowable
       t.body.result
     }
@@ -318,9 +325,9 @@ trait ThreadPoolTasks extends Tasks {
     val t = newTaskImpl(task)
 
     // debuglog("-----------> Executing with wait: " + task)
-    t.start
-
-    t.sync
+    t.start()
+    
+    t.sync()
     t.body.forwardThrowable
     t.body.result
   }
@@ -369,7 +376,7 @@ trait FutureThreadPoolTasks extends Tasks {
     def sync() = future.get
     def tryCancel = false
     def run = {
-      compute
+      compute()
     }
   }
 
diff --git a/src/library/scala/collection/parallel/immutable/ParHashMap.scala b/src/library/scala/collection/parallel/immutable/ParHashMap.scala
index 1fec522a93..e785932933 100644
--- a/src/library/scala/collection/parallel/immutable/ParHashMap.scala
+++ b/src/library/scala/collection/parallel/immutable/ParHashMap.scala
@@ -304,14 +304,21 @@ extends collection.parallel.BucketCombiner[(K, V), ParHashMap[K, V], (K, V), Has
       evaluateCombiners(trie)
       trie.asInstanceOf[HashMap[K, Repr]]
     }
-    private def evaluateCombiners(trie: HashMap[K, Combiner[V, Repr]]): Unit = trie match {
+    private def evaluateCombiners(trie: HashMap[K, Combiner[V, Repr]]): HashMap[K, Repr] = trie match {
       case hm1: HashMap.HashMap1[_, _] =>
-        hm1.asInstanceOf[HashMap.HashMap1[K, Repr]].value = hm1.value.result
-        hm1.kv = null
+        val evaledvalue = hm1.value.result
+        new HashMap.HashMap1[K, Repr](hm1.key, hm1.hash, evaledvalue, null)
       case hmc: HashMap.HashMapCollision1[_, _] =>
-        hmc.asInstanceOf[HashMap.HashMapCollision1[K, Repr]].kvs = hmc.kvs map { p => (p._1, p._2.result) }
-      case htm: HashMap.HashTrieMap[_, _] =>
-        for (hm <- htm.elems) evaluateCombiners(hm)
+        val evaledkvs = hmc.kvs map { p => (p._1, p._2.result) }
+        new HashMap.HashMapCollision1[K, Repr](hmc.hash, evaledkvs)
+      case htm: HashMap.HashTrieMap[k, v] =>
+        var i = 0
+        while (i < htm.elems.length) {
+          htm.elems(i) = evaluateCombiners(htm.elems(i)).asInstanceOf[HashMap[k, v]]
+          i += 1
+        }
+        htm.asInstanceOf[HashMap[K, Repr]]
+      case empty => empty.asInstanceOf[HashMap[K, Repr]]
     }
     def split = {
       val fp = howmany / 2
diff --git a/src/library/scala/collection/parallel/package.scala b/src/library/scala/collection/parallel/package.scala
index addc366072..f152629c50 100644
--- a/src/library/scala/collection/parallel/package.scala
+++ b/src/library/scala/collection/parallel/package.scala
@@ -117,7 +117,7 @@ package parallel {
   /** Composite throwable - thrown when multiple exceptions are thrown at the same time. */
   final case class CompositeThrowable(
     val throwables: Set[Throwable]
-  ) extends Throwable(
+  ) extends Exception(
     "Multiple exceptions thrown during a parallel computation: " +
       throwables.map(t => t + "\n" + t.getStackTrace.take(10).++("...").mkString("\n")).mkString("\n\n")
   )
diff --git a/src/library/scala/math/BigInt.scala b/src/library/scala/math/BigInt.scala
index 361e02cb16..8a53afaa62 100644
--- a/src/library/scala/math/BigInt.scala
+++ b/src/library/scala/math/BigInt.scala
@@ -309,7 +309,7 @@ class BigInt(val bigInteger: BigInteger) extends ScalaNumber with ScalaNumericCo
   override def byteValue   = intValue.toByte
 
   /** Converts this BigInt to a <tt>short</tt>.
-   *  If the BigInt is too big to fit in a byte, only the low-order 16 bits are returned.
+   *  If the BigInt is too big to fit in a short, only the low-order 16 bits are returned.
    *  Note that this conversion can lose information about the overall magnitude of the
    *  BigInt value as well as return a result with the opposite sign.
    */
@@ -323,7 +323,7 @@ class BigInt(val bigInteger: BigInteger) extends ScalaNumber with ScalaNumericCo
   def charValue   = intValue.toChar
 
   /** Converts this BigInt to an <tt>int</tt>.
-   *  If the BigInt is too big to fit in a char, only the low-order 32 bits
+   *  If the BigInt is too big to fit in a int, only the low-order 32 bits
    *  are returned. Note that this conversion can lose information about the
    *  overall magnitude of the BigInt value as well as return a result with
    *  the opposite sign.
@@ -331,7 +331,7 @@ class BigInt(val bigInteger: BigInteger) extends ScalaNumber with ScalaNumericCo
   def intValue    = this.bigInteger.intValue
 
   /** Converts this BigInt to a <tt>long</tt>.
-   *  If the BigInt is too big to fit in a char, only the low-order 64 bits
+   *  If the BigInt is too big to fit in a long, only the low-order 64 bits
    *  are returned. Note that this conversion can lose information about the
    *  overall magnitude of the BigInt value as well as return a result with
    *  the opposite sign.
diff --git a/src/library/scala/reflect/api/Names.scala b/src/library/scala/reflect/api/Names.scala
index e226d2265a..9498f0af36 100755
--- a/src/library/scala/reflect/api/Names.scala
+++ b/src/library/scala/reflect/api/Names.scala
@@ -1,32 +1,59 @@
 package scala.reflect
 package api
 
+/** A trait that manages names.
+ *  A name is a string in one of two name universes: terms and types.
+ *  The same string can be a name in both universes.
+ *  Two names are equal if they represent the same string and they are
+ *  members of the same universe.
+ * 
+ *  Names are interned. That is, for two names `name11 and `name2`,
+ *  `name1 == name2` implies `name1 eq name2`.
+ */
 trait Names {
-
+  
+  /** The abstract type of names */
   type Name >: Null <: AbsName
+
+  /** The abstract type of names representing terms */
   type TypeName <: Name
+
+  /** The abstract type of names representing types */
   type TermName <: Name
 
   abstract class AbsName {
+    /** Is this name a term name? */
     def isTermName: Boolean
+
+    /** Is this name a type name? */
     def isTypeName: Boolean
+
+    /** Returns a term name that represents the same string as this name */
     def toTermName: TermName
+
+    /** Returns a type name that represents the same string as this name */
     def toTypeName: TypeName
 
-    /** Replace all occurrences of $op_names in this name by corresponding operator symbols.
+    /** Replaces all occurrences of $op_names in this name by corresponding operator symbols.
      *  Example: `foo_+=` becomes `foo_$plus$eq`.
      */
     def decode: String
 
-    /** Replace all occurrences of operator symbols in this name by corresponding $op_names.
+    /** Replaces all occurrences of operator symbols in this name by corresponding $op_names.
      *  Example: `foo_$plus$eq` becomes `foo_+=`
      */
     def encode: Name
   }
 
+  /** Create a new term name.
+   */
   def newTermName(s: String): TermName
+
+  /** Creates a new type name.
+   */
   def newTypeName(s: String): TypeName
 
   def EmptyTermName: TermName = newTermName("")
+
   def EmptyTypeName: TypeName = EmptyTermName.toTypeName
 }
diff --git a/src/library/scala/reflect/api/StandardDefinitions.scala b/src/library/scala/reflect/api/StandardDefinitions.scala
index 6b480ab83d..08071660a2 100755
--- a/src/library/scala/reflect/api/StandardDefinitions.scala
+++ b/src/library/scala/reflect/api/StandardDefinitions.scala
@@ -12,9 +12,7 @@ trait StandardDefinitions { self: Universe =>
 
   abstract class AbsDefinitions {
     // outer packages and their classes
-    // Under consideration
-    // def RootPackage: Symbol
-
+    def RootPackage: Symbol
     def RootClass: Symbol
     def EmptyPackage: Symbol
     def EmptyPackageClass: Symbol
diff --git a/src/library/scala/reflect/api/Symbols.scala b/src/library/scala/reflect/api/Symbols.scala
index 8b4b170847..01c1a0f2ae 100755
--- a/src/library/scala/reflect/api/Symbols.scala
+++ b/src/library/scala/reflect/api/Symbols.scala
@@ -15,7 +15,14 @@ trait Symbols { self: Universe =>
      */
     def hasModifier(mod: Modifier.Value): Boolean
 
-    /** The owner of this symbol.
+    /** The owner of this symbol. This is the symbol
+     *  that directly contains the current symbol's definition.
+     *  The `NoSymbol` symbol does not have an owner, and calling this method
+     *  on one causes an internal error.
+     *  The owner of the Scala root class [[scala.reflect.api.mirror.RootClass]]
+     *  and the Scala root object [[scala.reflect.api.mirror.RootPackage]] is `NoSymbol`.
+     *  Every other symbol has a chain of owners that ends in
+     *  [[scala.reflect.api.mirror.RootClass]].
      */
     def owner: Symbol
 
@@ -74,23 +81,6 @@ trait Symbols { self: Universe =>
      */
     def annotations: List[self.AnnotationInfo]
 
-    /** The type of the symbol
-     */
-    def tpe: Type
-
-    /** The info of the symbol. This is like tpe, except for class symbols where the `info`
-     *  describes the contents of the class whereas the `tpe` is a reference to the class.
-     */
-    def info: Type
-
-    /** If this symbol is a class or trait, its self type, otherwise the type of the symbol itself
-     */
-    def typeOfThis: Type
-
-    /** The type `C.this`, where `C` is the current class.
-     */
-    def thisType: Type
-
     /** For a class: the module or case class factory with the same name in the same package.
      *  For all others: NoSymbol
      */
@@ -114,20 +104,43 @@ trait Symbols { self: Universe =>
     /** The top-level class containing this symbol. */
     def toplevelClass: Symbol
 
-    /** The next enclosing class */
+    /** The next enclosing class, or `NoSymbol` if none exists */
     def enclClass      : Symbol
 
-    /** The next enclosing method */
+    /** The next enclosing method, or `NoSymbol` if none exists */
     def enclMethod     : Symbol
 
+    /** Does this symbol represent the definition of term?
+     *  Note that every symbol is either a term or a type.
+     *  So for every symbol `sym`, either `sym.isTerm` is true
+     *  or `sym.isType` is true.
+     */
     def isTerm         : Boolean
+
+    /** Does this symbol represent the definition of type?
+     *  Note that every symbol is either a term or a type.
+     *  So for every symbol `sym`, either `sym.isTerm` is true
+     *  or `sym.isType` is true.
+     */
     def isType         : Boolean
+
+    /** Does this symbol represent the definition of class?
+     *  If yes, `isType` is also guaranteed to be true.
+     */
     def isClass        : Boolean
+
+    /** Does this symbol represent the definition of a type alias?
+     *  If yes, `isType` is also guaranteed to be true.
+     */
     def isAliasType    : Boolean
+
+    /** Does this symbol represent the definition of an abstract type?
+     *  If yes, `isType` is also guaranteed to be true.
+     */
     def isAbstractType : Boolean
 
     /** The type signature of this symbol.
-     *  Note if symbol is a member of a class, one almost always is interested
+     *  Note if the symbol is a member of a class, one almost always is interested
      *  in `typeSigIn` with a site type instead.
      */
     def typeSig: Type
@@ -136,22 +149,44 @@ trait Symbols { self: Universe =>
      */
     def typeSigIn(site: Type): Type
 
-    /** The type constructor corresponding to this type symbol.
-     */
-    def asTypeConstructor: Type  // needed by LiftCode
-
-   /** A type reference that refers to this type symbol
+   /**  A type reference that refers to this type symbol
      *  Note if symbol is a member of a class, one almost always is interested
      *  in `asTypeIn` with a site type instead.
+     *
+     *  Example: Given a class declaration `class C[T] { ... } `, that generates a symbol
+     *  `C`. Then `C.asType` is the type `C[T]`.
+     *
+     *  By contrast, `C.typeSig` would be a type signature of form
+     *  `PolyType(ClassInfoType(...))` that describes type parameters, value
+     *  parameters, parent types, and members of `C`.
      */
     def asType: Type
 
-    /** A type reference that refers to this type symbol seen as a member of given type `site`.
+    /** A type reference that refers to this type symbol seen
+     *  as a member of given type `site`.
      */
     def asTypeIn(site: Type): Type
 
+    /** The type constructor corresponding to this type symbol.
+     *  This is different from `asType` in that type parameters
+     *  are part of results of `asType`, but not of `asTypeConstructor`.
+     *
+     *  Example: Given a class declaration `class C[T] { ... } `, that generates a symbol
+     *  `C`. Then `C.asType` is the type `C[T]`, but `C.asTypeCponstructor` is `C`.
+     */
+    def asTypeConstructor: Type  // needed by LiftCode
+
+    /** If this symbol is a class or trait, its self type, otherwise the type
+     *  of the symbol itself.
+     */
+    def typeOfThis: Type
+
+    /** If this symbol is a class, the type `C.this`, otherwise `NoPrefix`.
+     */
+    def thisType: Type
+
     /** A fresh symbol with given name `name`, position `pos` and flags `flags` that has
-     *  the current symbol as its owner.
+     *  the current symbol as its owner. 
      */
     def newNestedSymbol(name: Name, pos: Position, flags: Long): Symbol // needed by LiftCode
 
diff --git a/src/library/scala/reflect/api/Trees.scala b/src/library/scala/reflect/api/Trees.scala
index 2394925657..03b043c188 100644
--- a/src/library/scala/reflect/api/Trees.scala
+++ b/src/library/scala/reflect/api/Trees.scala
@@ -8,9 +8,8 @@ package api
 
 import scala.collection.mutable.ListBuffer
 
-//import scala.tools.nsc.util.{ FreshNameCreator, HashSet, SourceFile }
-
-trait Trees /*extends reflect.generic.Trees*/ { self: Universe =>
+// Syncnote: Trees are currently not thread-safe.
+trait Trees { self: Universe =>
 
   private[scala] var nodeCount = 0
 
@@ -549,7 +548,7 @@ trait Trees /*extends reflect.generic.Trees*/ { self: Universe =>
     Select(qualifier, sym.name) setSymbol sym
 
   /** Identifier <name> */
-  case class Ident(name: Name) extends RefTree { }
+  case class Ident(name: Name) extends RefTree
 
   def Ident(name: String): Ident =
     Ident(newTermName(name))
diff --git a/src/library/scala/reflect/api/Types.scala b/src/library/scala/reflect/api/Types.scala
index 4b959649fd..6185a788ae 100755
--- a/src/library/scala/reflect/api/Types.scala
+++ b/src/library/scala/reflect/api/Types.scala
@@ -20,7 +20,7 @@ trait Types { self: Universe =>
 
     /** The collection of declarations in this type
      */
-    def allDeclarations: Iterable[Symbol]
+    def declarations: Iterable[Symbol]
 
     /** The member with given name, either directly declared or inherited,
      *  an OverloadedSymbol if several exist, NoSymbol if none exist.
@@ -36,7 +36,7 @@ trait Types { self: Universe =>
      *  Members appear in the linearization order of their owners.
      *  Members with the same owner appear in reverse order of their declarations.
      */
-    def allMembers: Iterable[Symbol]
+    def members: Iterable[Symbol]
 
     /** An iterable containing all non-private members of this type (directly declared or inherited)
      *  Members appear in the linearization order of their owners.
@@ -125,19 +125,23 @@ trait Types { self: Universe =>
 
     /** Does this type contain a reference to given symbol? */
     def contains(sym: Symbol): Boolean
-  }
 
-  /** This class declares methods that are visible in a `SingleType`.
-   */
-  trait AbsSingletonType extends AbsType {
+    /** If this is a compound type, the list of its parent types;
+     *  otherwise the empty list
+     */
+    def parents: List[Type]
 
-    /** The type underlying a singleton type */
+    /** If this is a singleton type, returns the type underlying it;
+     *  otherwise returns this type itself.
+     */
     def underlying: Type
 
-    /** Widen from singleton type to its underlying non-singleton
-     *  base type by applying one or more `underlying` dereferences,
-     *  identity for all other types.
+    /** If this is a singleton type, widen it to its nearest underlying non-singleton
+     *  base type by applying one or more `underlying` dereferences.
+     *  If this is not a singlecon type, returns this type itself.
      *
+     *  Example:
+     * 
      *  class Outer { class C ; val x: C }
      *  val o: Outer
      *  <o.x.type>.widen = o.C
@@ -145,19 +149,6 @@ trait Types { self: Universe =>
     def widen: Type
   }
 
-  /** This class declares methods that are visible in a `CompoundType` (i.e.
-   *  a class/trait/object template or refined type of the form
-   *  {{{
-   *     P_1 with ... with P_m { D_1; ...; D_n }
-   *  }}}
-   *  P_n
-   */
-  trait AbsCompoundType extends AbsType {
-
-    /** The list of parent types of this compound type */
-    def parents: List[Type]
-  }
-
   /** The type of Scala types, and also Scala type signatures.
    *  (No difference is internally made between the two).
    */
@@ -293,7 +284,7 @@ trait Types { self: Universe =>
 
   /** A subtype of Type representing refined types as well as `ClassInfo` signatures.
    */
-  type CompoundType <: /*AbsCompoundType with*/ Type
+  type CompoundType <: Type
 
   /** The `RefinedType` type defines types of any of the forms on the left,
    *  with their RefinedType representations to the right.