reflection docs improvements and moves to doc page

1 files changed, 11 insertions, 24 deletions

diff --git a/src/reflect/scala/reflect/api/Names.scala b/src/reflect/scala/reflect/api/Names.scala
index c1de49a475..dccdd6868b 100644
--- a/src/reflect/scala/reflect/api/Names.scala
+++ b/src/reflect/scala/reflect/api/Names.scala
@@ -1,33 +1,20 @@
 package scala.reflect
 package api
 
-/** A slice of [[scala.reflect.api.Universe the Scala reflection cake]] that defines names and operations on them.
- *  See [[scala.reflect.api.Universe]] for a description of how the reflection API is encoded with the cake pattern.
- *
- *  Scala has separate namespaces for term names and type names. For example it is possible to have
- *  a class named `C` and an object named `C` declared in the same lexical scope.
- *
- *  Therefore the Scala reflection API models names using strongly-typed objects rather than strings:
- *  [[scala.reflect.api.Names#TermName]] and [[scala.reflect.api.Names#TypeName]].
- *
- *  A Name wraps a string as the name for either a type ([[TypeName]]) of a term ([[TermName]]).
- *  Two names are equal, if the wrapped string are equal and they are either both `TypeName` or both `TermName`.
- *  The same string can co-exist as a `TypeName` and a `TermName`, but they would not be equal.
- *  Names are interned. That is, for two names `name1` and `name2`, `name1 == name2` implies `name1 eq name2`.
- *  Name instances also can perform mangling and unmangling of symbolic names.
- *
+/** This trait defines Names (a Scala reflection concept) and operations on them.
+ *  
+ *  Names are simple wrappers for strings. [[scala.reflect.api.Names#Name Name]] has two subtypes [[scala.reflect.api.Names#TermName TermName]] and [[scala.reflect.api.Names#TypeName TypeName]] which
+ *  distinguish names of terms (like objects or members) and types. A term and a type of the
+ *  same name can co-exist in an object. 
+ *  
+ *  @see [[http://docs.scala-lang.org/overviews/reflection/overview.html]].
+
  *  === Examples ===
  *
- *  To search for the `map` method declared in the `List` class, one uses
- *  `typeOf[List[_]].member(newTermName("map"))` to explicitly specify that a term is looked up.
- *
- *  An alternative notation makes use of implicit conversions from `String` to `TermName` and `TypeName`:
- *  `typeOf[List[_]].member("map": TermName)`. Note that there's no implicit conversion from `String` to `Name`,
- *  because it would be unclear whether such a conversion should produce a term name or a type name.
+ *  To search for the `map` method (which is a term) declared in the `List` class,
+ *  use `typeOf[List[_]].member(newTermName("map"))`. To search for a type member, use
+ *  newTypeName instead.
  *
- *  Finally some names that bear special meaning for the compiler are defined in [[scala.reflect.api.StandardNames]].
- *  For example, `WILDCARD` represents `_` and `CONSTRUCTOR` represents the standard JVM name for constructors, `<init>`.
- *  Prefer using such constants instead of spelling the names out explicitly.
  */
 trait Names {
   /** An implicit conversion from String to TermName.