From f96f4bf36db31c2783ead455697b6e6e8256f810 Mon Sep 17 00:00:00 2001
From: Vlad Ureche <vlad.ureche@gmail.com>
Date: Wed, 10 Oct 2012 11:45:01 +0200
Subject: scala.reflect.api.StandardNames documentation

---
 src/reflect/scala/reflect/api/StandardNames.scala | 34 ++++++++++++++++-------
 src/reflect/scala/reflect/api/Universe.scala      |  2 ++
 src/reflect/scala/reflect/api/package.scala       |  2 +-
 3 files changed, 27 insertions(+), 11 deletions(-)

(limited to 'src')

diff --git a/src/reflect/scala/reflect/api/StandardNames.scala b/src/reflect/scala/reflect/api/StandardNames.scala
index 8029450ca0..203bcdbdc4 100644
--- a/src/reflect/scala/reflect/api/StandardNames.scala
+++ b/src/reflect/scala/reflect/api/StandardNames.scala
@@ -10,24 +10,34 @@ package api
 //    Is it necessary to perform reflection (like ERROR or LOCAL_SUFFIX_STRING)? If yes, then sure.
 //    Otherwise you'd better not - reflection API should stay minimalistic.
 
-/** A slice of [[scala.reflect.api.Universe the Scala reflection cake]] that defines standard names.
+/** This trait is the [[scala.reflect.api.Universe reflection API]] component that defines standard [[Names names used in reflection and macros]].
  *
  *  Standard names are names that are essential to creating trees or to reflecting Scala artifacts.
  *  For example, `CONSTRUCTOR` (aka `<init>` on JVM) is necessary to create and invoke constructors.
  *
- *  These standard names can be referred to using `nme` for term names (listed in [[scala.reflect.api.StandardNames#TermNamesApi]])
- *  and using `tpnme` for type names (listed in [[scala.reflect.api.StandardNames#TypeNamesApi]])
+ *  These standard names can be referred to using [[nme `nme`]] for term names and [[tpnme `tpnme`]] for type names
+ *
+ *  @see [[Names]]
+ *
+ *  The API for names in Scala reflection.
+ *  @groupname StandardNames Standard Names
  */
 trait StandardNames {
   self: Universe =>
 
-  /** A value containing all standard term names. */
+  /** A value containing all [[TermNamesApi standard term names]].
+   *  @group StandardNames
+   */
   val nme: TermNamesApi
 
-  /** A value containing all standard type names. */
+  /** A value containing all [[TypeNamesApi standard type names]].
+   *  @group StandardNames
+   */
   val tpnme: TypeNamesApi
 
-  /** Defines standard names, common for term and type names. */
+  /** Defines standard names, common for term and type names: These can be accessed via the [[nme]] and [[tpnme]] members.
+   *  @group API
+   */
   trait NamesApi {
     /** An abstract type that represents the exact flavor of the name. */
     type NameType >: Null <: Name
@@ -39,8 +49,8 @@ trait StandardNames {
 
     /** The term or type name corresponding to an empty string.
      *  Represents an empty name, used to denote the fact that no name was specified
-     *  for `privateWithin` in [[scala.reflect.api.Trees#Modifiers]], for [[scala.reflect.api.Trees#This]],
-     *  for [[scala.reflect.api.Trees#Super]], etc.
+     *  for `privateWithin` in [[Trees#Modifiers]], for [[Trees#This]],
+     *  for [[Trees#Super]], etc.
      */
     val EMPTY: NameType
 
@@ -55,7 +65,9 @@ trait StandardNames {
     val PACKAGE: NameType
   }
 
-  /** Defines standard term names. */
+  /** Defines standard term names that can be accessed via the [[nme]] member.
+   *  @group API
+   */
   trait TermNamesApi extends NamesApi {
     /** @inheritdoc */
     type NameType = TermName
@@ -78,7 +90,9 @@ trait StandardNames {
     val LOCAL_SUFFIX_STRING: String
   }
 
-  /** Defines standard type names. */
+  /** Defines standard type names that can be accessed via the [[tpnme]] member.
+   *  @group API
+   */
   trait TypeNamesApi extends NamesApi {
     /** @inheritdoc */
     type NameType = TypeName
diff --git a/src/reflect/scala/reflect/api/Universe.scala b/src/reflect/scala/reflect/api/Universe.scala
index 207dc98a91..5bc5a7359b 100644
--- a/src/reflect/scala/reflect/api/Universe.scala
+++ b/src/reflect/scala/reflect/api/Universe.scala
@@ -70,6 +70,8 @@ package api
  * by an abstract type `X`, optionally together with a class `XApi` that defines `X`'s' interface.
  * `X`'s companion object, if it exists, is represented by a value `X` that is of type `XExtractor`.
  * Moreover, for each type `X`, there is a value `XTag` of type `ClassTag[X]` that allows to pattern match on `X`.
+ *
+ * @groupprio default 5
  */
 abstract class Universe extends Symbols
                            with Types
diff --git a/src/reflect/scala/reflect/api/package.scala b/src/reflect/scala/reflect/api/package.scala
index ba098cb3d5..db78a20fb5 100644
--- a/src/reflect/scala/reflect/api/package.scala
+++ b/src/reflect/scala/reflect/api/package.scala
@@ -4,7 +4,7 @@ import scala.reflect.api.{Universe => ApiUniverse}
 
 /** The Scala reflection API (located at scala-reflect.jar).
  *
- *  Using Scala reflection requires understanding of a couple of basic concepts like Symbols, Types, Mirror and Universes.
+ *  Using Scala reflection requires understanding of a couple of basic concepts like [[Symbols Symbols]], [[Types Types]], [[Mirror Mirrors]] and [[Universe Universes]].
  *  @see [[http://docs.scala-lang.org/overviews/reflection/overview.html]].
  *
  *  In Scala 2.10.0, reflection API and its implementation have experimental status. This means that the API and the docs are not complete and can be changed
-- 
cgit v1.2.3