SI-6399 Adds API docs for Any and AnyVal

- Updates AnyVal docs to address value classes.
- Updates Any docs to address universal traits.

2 files changed, 51 insertions, 5 deletions

diff --git a/src/library-aux/scala/Any.scala b/src/library-aux/scala/Any.scala
index 031b7d9d8c..07a9ffa8d5 100644
--- a/src/library-aux/scala/Any.scala
+++ b/src/library-aux/scala/Any.scala
@@ -10,6 +10,25 @@ package scala
 
 /** Class `Any` is the root of the Scala class hierarchy.  Every class in a Scala
  *  execution environment inherits directly or indirectly from this class.
+ *
+ * Starting with Scala 2.10 it is possible to directly extend `Any` using ''universal traits''.
+ * A ''universal trait'' is a trait that extends `Any`, only has `def`s as members, and does no initialization.
+ *
+ * The main use case for universal traits is to allow basic inheritance of methods for [[scala.AnyVal value classes]].
+ * For example,
+ *
+ * {{{
+ *     trait Printable extends Any {
+ *       def print(): Unit = println(this)
+ *     }
+ *     class Wrapper(val underlying: Int) extends AnyVal with Printable
+ *
+ *     val w = new Wrapper(3)
+ *     w.print()
+ * }}}
+ *
+ * See the [[http://docs.scala-lang.org/sips/pending/value-classes.html value classes guide]] for more
+ * details on the interplay of universal traits and value classes.
  */
 abstract class Any {
   /** Compares the receiver object (`this`) with the argument object (`that`) for equivalence.
diff --git a/src/library/scala/AnyVal.scala b/src/library/scala/AnyVal.scala
index d637527b30..ebdc963946 100644
--- a/src/library/scala/AnyVal.scala
+++ b/src/library/scala/AnyVal.scala
@@ -9,8 +9,8 @@
 package scala
 
 /** `AnyVal` is the root class of all ''value types'', which describe values
- *  not implemented as objects in the underlying host system.  The value classes
- *  are specified in SLS 12.2.
+ *  not implemented as objects in the underlying host system. Value classes
+ *  are specified in Scala Language Specification, section 12.2.
  *
  *  The standard implementation includes nine `AnyVal` subtypes:
  *
@@ -21,9 +21,36 @@ package scala
  *
  *  Other groupings:
  *
- *  The ''subrange types'' are [[scala.Byte]], [[scala.Short]], and [[scala.Char]].
- *  The ''integer types'' include the subrange types as well as [[scala.Int]] and [[scala.Long]].
- *  The ''floating point types'' are [[scala.Float]] and [[scala.Double]].
+ *   - The ''subrange types'' are [[scala.Byte]], [[scala.Short]], and [[scala.Char]].
+ *   - The ''integer types'' include the subrange types as well as [[scala.Int]] and [[scala.Long]].
+ *   - The ''floating point types'' are [[scala.Float]] and [[scala.Double]].
+ *
+ * Prior to Scala 2.10, `AnyVal` was a sealed trait. Beginning with Scala 2.10,
+ * however, it is possible to define a subclass of `AnyVal` called a ''user-defined value class''
+ * which is treated specially by the compiler. Properly-defined user value classes provide a way
+ * to improve performance on user-defined types by avoiding object allocation at runtime, and by
+ * replacing virtual method invocations with static method invocations.
+ *
+ * User-defined value classes which avoid object allocation...
+ *
+ *   - must have a single, public `val` parameter that is the underlying runtime representation.
+ *   - can define `def`s, but no `val`s, `var`s, or nested `traits`s, `class`es or `object`s.
+ *   - typically extend no other trait apart from `AnyVal`.
+ *   - cannot be used in type tests or pattern matching.
+ *   - may not override `equals` or `hashCode` methods.
+ *
+ * A minimal example:
+ * {{{
+ *     class Wrapper(val underlying: Int) extends AnyVal {
+ *       def foo: Wrapper = new Wrapper(underlying * 19)
+ *     }
+ * }}}
+ *
+ * It's important to note that user-defined value classes are limited, and in some circumstances,
+ * still must allocate a value class instance at runtime. These limitations and circumstances are
+ * explained in greater detail in the [[http://docs.scala-lang.org/overviews/core/value-classes.html Value Classes Guide]]
+ * as well as in [[http://docs.scala-lang.org/sips/pending/value-classes.html SIP-15: Value Classes]],
+ * the Scala Improvement Proposal.
  */
 abstract class AnyVal extends Any with NotNull {
   def getClass(): Class[_ <: AnyVal] = null