Improved documentation

Added explanations where suggested by Adriaan in his review.

Author: odersky

src/dotty/tools/dotc/core/Definitions.scala

@@ -437,13 +437,18 @@ class Definitions {
    *  to be the type parameters of a higher-kided type). This is a class symbol that
    *  would be generated by the following schema.
    *
-   *      class LambdaXYZ { type v_1 Arg1; ...; type v_N ArgN; type Apply }
+   *      class LambdaXYZ extends Object with P1 with ... with Pn {
+   *        type v_1 $hk$Arg0; ...; type v_N $hk$ArgN;
+   *        type Apply
+   *      }
    *
    *  Here:
    *
-   *   - XYZ is a string of length N with one letter for each variant of a bound symbols,
-   *     using `P` (positive variance), `N` (negative variance), `I` (invariant).
    *   - v_i are the variances of the bound symbols (i.e. +, -, or empty).
+   *   - XYZ is a string of length N with one letter for each variant of a bound symbol,
+   *     using `P` (positive variance), `N` (negative variance), `I` (invariant).
+   *   - for each positive or negative variance v_i there is a parent trait Pj which
+   *     is the same as LambdaXYZ except that it has `I` in i-th position.
    */
   def lambdaTrait(vcs: List[Int]): ClassSymbol = {
     assert(vcs.nonEmpty)

src/dotty/tools/dotc/core/TyperState.scala

@@ -23,7 +23,13 @@ class TyperState(r: Reporter) extends DotClass with Showable {
   /** The uninstantiated variables */
   def uninstVars = constraint.uninstVars
 
-  /** The ephemeral flag */
+  /** The ephemeral flag is set as a side effect if an operation accesses
+   *  the underlying type of a type variable. The reason we need this flag is
+   *  that any such operation is not referentially transparent; it might logically change
+   *  its value at the moment the type variable is instantiated. Caching code needs to
+   *  check the ephemeral flag; If the flag is set during an operation, the result
+   *  of that operation should not be cached.
+   */
   def ephemeral: Boolean = false
   def ephemeral_=(x: Boolean): Unit = ()
 

src/dotty/tools/dotc/core/Types.scala

@@ -654,7 +654,8 @@ object Types {
      *
      *    P { ... type T = / += / -= U ... } # T
      *
-     *  to just U
+     *  to just U. Does not perform the reduction if the resulting type would contain
+     *  a reference to the "this" of the current refined type.
      */
     def lookupRefined(name: Name)(implicit ctx: Context): Type = stripTypeVar match {
       case pre: RefinedType =>