SI-6371 adds comments for Trees#UnApply

Unfortunately we cannot remove this node, because it's emitted by typer
and, therefore, can be seen by macros and pickled as a part of annotations.
Therefore we have to expose UnApply in the API.

Experimental status of scala-reflect.jar will give us some leeway to evict it
from the compiler (and consequently from the API) by 2.10.1.

1 files changed, 23 insertions, 3 deletions

diff --git a/src/library/scala/reflect/base/Trees.scala b/src/library/scala/reflect/base/Trees.scala
index 74928a0cc6..78174f354c 100644
--- a/src/library/scala/reflect/base/Trees.scala
+++ b/src/library/scala/reflect/base/Trees.scala
@@ -605,10 +605,30 @@ trait Trees { self: Universe =>
     def unapply(bind: Bind): Option[(Name, Tree)]
   }
 
-  /** Noone knows what this is.
-   *  It is not idempotent w.r.t typechecking.
-   *  Can we, please, remove it?
+  /** Used to represent `unapply` methods in pattern matching.
    *  Introduced by typer, eliminated by patmat/explicitouter.
+   *
+   *  For example:
+   *  {{{
+   *    2 match { case Foo(x) => x }
+   *  }}}
+   *
+   *  Is represented as:
+   *  {{{
+   *    Match(
+   *      Literal(Constant(2)),
+   *      List(
+   *        CaseDef(
+   *          UnApply(
+   *            // a dummy node that carries the type of unapplication to patmat
+   *            // the <unapply-selector> here doesn't have an underlying symbol
+   *            // it only has a type assigned, therefore after `resetAllAttrs` this tree is no longer typeable
+   *            Apply(Select(Ident(Foo), newTermName("unapply")), List(Ident(newTermName("<unapply-selector>")))),
+   *            // arguments of the unapply => nothing synthetic here
+   *            List(Bind(newTermName("x"), Ident(nme.WILDCARD)))),
+   *          EmptyTree,
+   *          Ident(newTermName("x")))))
+   *  }}}
    */
   type UnApply >: Null <: TermTree