Added doc comments to Names trait.

1 files changed, 30 insertions, 3 deletions

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
 }