SI-6696 removes "helper" tree factory methods

As experience shows, these methods can easily be a source of confusion
for the newcomers: https://issues.scala-lang.org/browse/SI-6696.

I'm only leaving the TypeTree(tp) factory, since the facility to
set underlying types for type trees is not exposed in the public API,
as it's inherently mutable.

1 files changed, 39 insertions, 5 deletions

diff --git a/src/reflect/scala/reflect/api/Trees.scala b/src/reflect/scala/reflect/api/Trees.scala
index c98107f9b5..c547a1e467 100644
--- a/src/reflect/scala/reflect/api/Trees.scala
+++ b/src/reflect/scala/reflect/api/Trees.scala
@@ -1611,14 +1611,23 @@ trait Trees { self: Universe =>
    *  This node always occurs in the following context:
    *
    *    (`new` tpt).<init>[targs](args)
+   *
+   *  For example, an AST representation of:
+   *
+   *    new Example[Int](2)(3)
+   *
+   *  is the following code:
+   *
+   *    Apply(
+   *      Apply(
+   *        TypeApply(
+   *          Select(New(TypeTree(typeOf[Example])), nme.CONSTRUCTOR)
+   *          TypeTree(typeOf[Int])),
+   *        List(Literal(Constant(2)))),
+   *      List(Literal(Constant(3))))
    *  @group Extractors
    */
   abstract class NewExtractor {
-    /** A user level `new`.
-     *  One should always use this factory method to build a user level `new`.
-     *
-     *  @param tpt    a class type
-     */
     def apply(tpt: Tree): New
     def unapply(new_ : New): Option[Tree]
   }
@@ -2371,118 +2380,141 @@ trait Trees { self: Universe =>
   /** A factory method for `ClassDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical ClassDef constructor to create a class and then initialize its position and symbol manually", "2.10.1")
   def ClassDef(sym: Symbol, impl: Template): ClassDef
 
   /** A factory method for `ModuleDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical ModuleDef constructor to create an object and then initialize its position and symbol manually", "2.10.1")
   def ModuleDef(sym: Symbol, impl: Template): ModuleDef
 
   /** A factory method for `ValDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical ValDef constructor to create a val and then initialize its position and symbol manually", "2.10.1")
   def ValDef(sym: Symbol, rhs: Tree): ValDef
 
   /** A factory method for `ValDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical ValDef constructor to create a val with an empty right-hand side and then initialize its position and symbol manually", "2.10.1")
   def ValDef(sym: Symbol): ValDef
 
   /** A factory method for `ValDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical DefDef constructor to create a method and then initialize its position and symbol manually", "2.10.1")
   def DefDef(sym: Symbol, mods: Modifiers, vparamss: List[List[ValDef]], rhs: Tree): DefDef
 
   /** A factory method for `ValDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical DefDef constructor to create a method and then initialize its position and symbol manually", "2.10.1")
   def DefDef(sym: Symbol, vparamss: List[List[ValDef]], rhs: Tree): DefDef
 
   /** A factory method for `ValDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical DefDef constructor to create a method and then initialize its position and symbol manually", "2.10.1")
   def DefDef(sym: Symbol, mods: Modifiers, rhs: Tree): DefDef
 
   /** A factory method for `ValDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical DefDef constructor to create a method and then initialize its position and symbol manually", "2.10.1")
   def DefDef(sym: Symbol, rhs: Tree): DefDef
 
   /** A factory method for `ValDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical DefDef constructor to create a method and then initialize its position and symbol manually", "2.10.1")
   def DefDef(sym: Symbol, rhs: List[List[Symbol]] => Tree): DefDef
 
   /** A factory method for `TypeDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical TypeDef constructor to create a type alias and then initialize its position and symbol manually", "2.10.1")
   def TypeDef(sym: Symbol, rhs: Tree): TypeDef
 
   /** A factory method for `TypeDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical TypeDef constructor to create an abstract type or type parameter and then initialize its position and symbol manually", "2.10.1")
   def TypeDef(sym: Symbol): TypeDef
 
   /** A factory method for `LabelDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical LabelDef constructor to create a label and then initialize its position and symbol manually", "2.10.1")
   def LabelDef(sym: Symbol, params: List[Symbol], rhs: Tree): LabelDef
 
   /** A factory method for `Block` nodes.
    *  Flattens directly nested blocks.
    *  @group Factories
    */
+  @deprecated("Use the canonical Block constructor, explicitly specifying its expression if necessary. Flatten directly nested blocks manually if needed", "2.10.1")
   def Block(stats: Tree*): Block
 
   /** A factory method for `CaseDef` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical CaseDef constructor passing EmptyTree for guard", "2.10.1")
   def CaseDef(pat: Tree, body: Tree): CaseDef
 
   /** A factory method for `Bind` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical Bind constructor to create a bind and then initialize its symbol manually", "2.10.1")
   def Bind(sym: Symbol, body: Tree): Bind
 
   /** A factory method for `Try` nodes.
    *  @group Factories
    */
+  @deprecated("Use canonical CaseDef constructors to to create exception catching expressions and then wrap them in Try", "2.10.1")
   def Try(body: Tree, cases: (Tree, Tree)*): Try
 
   /** A factory method for `Throw` nodes.
    *  @group Factories
    */
+  @deprecated("Use the canonical New constructor to create an object instantiation expression and then wrap it in Throw", "2.10.1")
   def Throw(tpe: Type, args: Tree*): Throw
 
   /** Factory method for object creation `new tpt(args_1)...(args_n)`
    *  A `New(t, as)` is expanded to: `(new t).<init>(as)`
    *  @group Factories
    */
+  @deprecated("Use Apply(...Apply(Select(New(tpt), nme.CONSTRUCTOR), args1)...argsN) instead", "2.10.1")
   def New(tpt: Tree, argss: List[List[Tree]]): Tree
 
   /** 0-1 argument list new, based on a type.
    *  @group Factories
    */
+  @deprecated("Use New(TypeTree(tpe), args.toList) instead", "2.10.1")
   def New(tpe: Type, args: Tree*): Tree
 
   /** 0-1 argument list new, based on a symbol.
    *  @group Factories
    */
+  @deprecated("Use New(sym.toType, args) instead", "2.10.1")
   def New(sym: Symbol, args: Tree*): Tree
 
   /** A factory method for `Apply` nodes.
    *  @group Factories
    */
+  @deprecated("Use Apply(Ident(sym), args.toList) instead", "2.10.1")
   def Apply(sym: Symbol, args: Tree*): Tree
 
   /** 0-1 argument list new, based on a type tree.
    *  @group Factories
    */
+  @deprecated("Use Apply(Select(New(tpt), nme.CONSTRUCTOR), args) instead", "2.10.1")
   def ApplyConstructor(tpt: Tree, args: List[Tree]): Tree
 
   /** A factory method for `Super` nodes.
    *  @group Factories
    */
+  @deprecated("Use Super(This(sym), mix) instead", "2.10.1")
   def Super(sym: Symbol, mix: TypeName): Tree
 
   /** A factory method for `This` nodes.
@@ -2494,6 +2526,7 @@ trait Trees { self: Universe =>
    *  The string `name` argument is assumed to represent a [[scala.reflect.api.Names#TermName `TermName`]].
    *  @group Factories
    */
+  @deprecated("Use Select(tree, newTermName(name)) instead", "2.10.1")
   def Select(qualifier: Tree, name: String): Select
 
   /** A factory method for `Select` nodes.
@@ -2504,6 +2537,7 @@ trait Trees { self: Universe =>
   /** A factory method for `Ident` nodes.
    *  @group Factories
    */
+  @deprecated("Use Ident(newTermName(name)) instead", "2.10.1")
   def Ident(name: String): Ident
 
   /** A factory method for `Ident` nodes.