Working on the documentation of core classes.

withdraw some of the goodness I banked a while ago with the AnyVal
types. Started on what will culminate in the total elimination of
SourcelessComments. Cleaned up the docs on ancient classes like Product.
More to come. No review.

14 files changed, 401 insertions, 161 deletions

diff --git a/src/compiler/scala/tools/cmd/gen/AnyVals.scala b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
index f6f48359cd..db07229ce9 100644
--- a/src/compiler/scala/tools/cmd/gen/AnyVals.scala
+++ b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
@@ -7,8 +7,20 @@ package scala.tools.cmd
 package gen
 
 trait AnyValTemplates {
+  def indent(s: String) = if (s == "") "" else "  " + s
+  def indentN(s: String) = s.lines map indent mkString "\n"
+
+def classDocTemplate = ("""
+/** `@name@` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.@name@]] => [[scala.runtime.Rich@name@]]
+ *  which provides useful non-primitive operations.
+ */
+""".trim + "\n")
+
   def timestampString = ""
-  def template = ("""
+  def headerTemplate = ("""
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
 **    / __/ __// _ | / /  / _ |    (c) 2002-2011, LAMP/EPFL             **
@@ -20,11 +32,32 @@ trait AnyValTemplates {
 %s
 package scala
 
-import java.{ lang => jl }
-  """.trim.format(timestampString) + "\n\n"
-  )
+""".trim.format(timestampString) + "\n\n")
+
+  def nonUnitCompanion = """
+/** Transform a value type into a boxed reference type.
+ *
+ *  @param  x   the @name@ to be boxed
+ *  @return     a @type@ offering `x` as its underlying value.
+ */
+def box(x: @name@): @type@ = @type@.valueOf(x)
+
+/** Transform a boxed type into a value type.  Note that this
+ *  method is not typesafe: it accepts any Object, but will throw
+ *  an exception if the argument is not a @type@.
+ *
+ *  @param  x   the @name@ to be unboxed.
+ *  @throws     ClassCastException  if the argument is not a @type@
+ *  @return     the @name@ resulting from calling @lcname@Value() on `x`
+ */
+def unbox(x: java.lang.Object): @name@ = x.asInstanceOf[@type@].@lcname@Value()
 
-  def booleanBody = """
+/** The String representation of the scala.@name@ companion object.
+ */
+override def toString = "object scala.@name@"
+  """
+
+  def booleanBody = ("""
 final class Boolean extends AnyVal {
   def unary_! : Boolean = sys.error("stub")
 
@@ -41,34 +74,35 @@ final class Boolean extends AnyVal {
 }
 
 object Boolean extends AnyValCompanion {
-  override def toString = "object scala.Boolean"
-  def box(x: Boolean): jl.Boolean = jl.Boolean.valueOf(x)
-  def unbox(x: jl.Object): Boolean = x.asInstanceOf[jl.Boolean].booleanValue()
-}
-  """.trim
+""".trim + indentN(nonUnitCompanion) + "\n}")
 
   def unitBody = """
 import runtime.BoxedUnit
 
+/** Unit is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.  There is
+ *  only one value of type Unit: `()`.
+ */
 final class Unit extends AnyVal { }
 
 object Unit extends AnyValCompanion {
   override def toString = "object scala.Unit"
   def box(x: Unit): BoxedUnit = BoxedUnit.UNIT
-  def unbox(x: jl.Object): Unit = ()
+  def unbox(x: java.lang.Object): Unit = ()
 }
   """.trim
 
-  def cardinalCompanion = """
+  def cardinalCompanion = ("""
+/** The smallest value representable as a @name@.
+ */
 final val MinValue = @type@.MIN_VALUE
-final val MaxValue = @type@.MAX_VALUE
 
-def box(x: @name@): @type@ = @type@.valueOf(x)
-def unbox(x: jl.Object): @name@ = x.asInstanceOf[@type@].@lcname@Value()
-override def toString = "object scala.@name@"
-  """.trim.lines
+/** The largest value representable as a @name@.
+ */
+final val MaxValue = @type@.MAX_VALUE
+""" + nonUnitCompanion).trim.lines
 
-  def floatingCompanion = """
+  def floatingCompanion = ("""
 /** The smallest positive value greater than @zero@.*/
 final val MinPositiveValue = @type@.MIN_VALUE
 final val NaN              = @type@.NaN
@@ -87,14 +121,32 @@ final val MinValue = -@type@.MAX_VALUE
 
 /** The largest finite positive number representable as a @name@. */
 final val MaxValue = @type@.MAX_VALUE
-
-def box(x: @name@): @type@ = @type@.valueOf(x)
-def unbox(x: jl.Object): @name@ = x.asInstanceOf[@type@].@lcname@Value()
-override def toString = "object scala.@name@"
-  """.trim.lines
+""" + nonUnitCompanion).trim.lines
 }
 
 class AnyVals extends AnyValTemplates {
+  trait AnyValInterpolation {
+    def name: String
+    def isCardinal: Boolean
+    def restype: String
+    def tpe: String
+    def zero: String
+
+    lazy val interpolations = Map(
+      "@restype@"  -> restype,
+      "@name@"     -> name,
+      "@type@"     -> tpe,
+      "@lcname@"   -> name.toLowerCase,
+      "@zero@"     -> zero
+    )
+    def interpolate(s: String): String = interpolations.foldLeft(s) {
+      case (str, (key, value)) => str.replaceAll(key, value)
+    }
+
+    def classDoc = interpolate(classDocTemplate)
+    def make(): String
+  }
+
   val B = "Byte"
   val S = "Short"
   val C = "Char"
@@ -107,19 +159,38 @@ class AnyVals extends AnyValTemplates {
   lazy val floating = List(F, D)
   lazy val numeric  = cardinal ++ floating
 
-  def javaType(primType: String) = "jl." + (primType match {
+  def javaType(primType: String) = "java.lang." + (primType match {
     case C => "Character"
     case I => "Integer"
     case t => t
   })
 
-  def make() =
-    (numeric zip (numeric map (name => new AnyValOps(name).make()))) ++ List(
-      ("Boolean", template + booleanBody),
-      ("Unit", template + unitBody)
-    )
+  def make() = {
+    val nums = numeric map (name => new AnyValOps(name).make())
+    (numeric zip nums) :+ ("Boolean", makeBoolean()) :+ ("Unit", makeUnit())
+  }
+
+  def makeBoolean() = (new AnyValInterpolation {
+    def name       = "Boolean"
+    def isCardinal = false
+    def restype    = "Nothing"
+    def tpe        = "java.lang.Boolean"
+    def zero       = "false"
+
+    def make() = headerTemplate + classDoc + interpolate(booleanBody)
+  }).make()
+
+  def makeUnit() = (new AnyValInterpolation {
+    def name       = "Unit"
+    def isCardinal = false
+    def restype    = "Nothing"
+    def tpe        = "scala.runtime.BoxedUnit"
+    def zero       = "()"
 
-  class AnyValOps(name: String) {
+    def make() = headerTemplate + unitBody
+  }).make()
+
+  class AnyValOps(val name: String) extends AnyValInterpolation {
     val isCardinal = cardinal contains name
     val restype    = if ("LFD" contains name.head) name else I
     val tpe        = javaType(name)
@@ -129,14 +200,6 @@ class AnyVals extends AnyValTemplates {
       case 'D' => "0.0d"
       case _   => "0"
     }
-    val interpolations = Map(
-      "@restype@"  -> restype,
-      "@name@"     -> name,
-      "@type@"     -> tpe,
-      "@lcname@"   -> name.toLowerCase,
-      "@zero@"     -> zero
-    )
-
     def mkCoercions = numeric map (x => "def to%s: %s".format(x, x))
     def mkUnaryOps  = unaryops map (op => "def unary_%s : @restype@".format(op))
     def mkCommon    = List(
@@ -158,7 +221,6 @@ class AnyVals extends AnyValTemplates {
     }
 
     def defImplementation = "sys.error(\"stub\")"
-    def indent(s: String) = if (s == "") "" else "  " + s
     def mkClass = {
       val lines = clumps.foldLeft(List[String]()) {
         case (res, Nil)   => res
@@ -169,7 +231,7 @@ class AnyVals extends AnyValTemplates {
           }
           res ++ xs
       }
-      assemble("final class", "AnyVal", lines)
+      classDoc + assemble("final class", "AnyVal", lines)
     }
     def mkObject = assemble("object", "AnyValCompanion", companionBody map interpolate toList)
 
@@ -179,11 +241,7 @@ class AnyVals extends AnyValTemplates {
       "}"
     ).mkString("\n", "\n", "\n")
 
-    def make() = template + mkClass + "\n" + mkObject
-
-    def interpolate(s: String): String = interpolations.foldLeft(s) {
-      case (str, (key, value)) => str.replaceAll(key, value)
-    }
+    def make() = headerTemplate + mkClass + "\n" + mkObject
 
     /** Makes a set of binary operations based on the given set of ops, args, and resultFn.
      *
diff --git a/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
index 6ce2feea84..6b6886a599 100644
--- a/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
+++ b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
@@ -210,39 +210,6 @@ abstract class SourcelessComments {
 
     /*******************************************************************/
 
-    comment(AnyValClass) = new DocComment("""
-      /** Class `AnyVal` is the root class of all ''value types''.
-        *
-        * `AnyVal` has a fixed number of subclasses, which describe values which are not implemented as objects in the
-        * underlying host system.
-        *
-        * Classes [[scala.Double]], [[scala.Float]], [[scala.Long]], [[scala.Int]], [[scala.Char]], [[scala.Short]],
-        * and [[scala.Byte]] are together called ''numeric value types''. Classes [[scala.Byte]], [[scala.Short]], and
-        * [[scala.Char]] are called ''subrange types''. Subrange types, as well as [[scala.Int]] and [[scala.Long]] are
-        * called ''integer types'', whereas [[scala.Float]] and [[scala.Double]] are called ''floating point types''. */
-      """)
-
-    comment(BooleanClass) = new DocComment("""
-      /** Class `Boolean` has only two values: `true` and `false`. */
-      """)
-
-    comment(UnitClass) = new DocComment("""
-      /** Class `Unit` has only one value: `()`. */
-      """)
-
-    List(ByteClass, CharClass, DoubleClass, LongClass, FloatClass, IntClass, ShortClass) foreach { sym =>
-      val maxValue = "MAX_" + sym.name.toString().toUpperCase()
-      val minValue = "MIN_" + sym.name.toString().toUpperCase()
-      comment(sym) = new DocComment("""
-        /** Class `""" + sym.name + """` belongs to the value classes whose instances are not represented as objects by
-          * the underlying host system.  There is an implicit conversion from instances of `""" + sym.name + """` to
-          * instances of [[scala.runtime.Rich""" + sym.name + """]] which provides useful non-primitive operations.
-          * All value classes inherit from class [[scala.AnyVal]].
-          *
-          * Values `""" + maxValue + """` and `""" + minValue + """` are defined in object [[scala.Math]]. */
-        """)
-    }
-
     comment
   }
 
diff --git a/src/library/scala/AnyVal.scala b/src/library/scala/AnyVal.scala
index 4b4b6038d1..850042700f 100755
--- a/src/library/scala/AnyVal.scala
+++ b/src/library/scala/AnyVal.scala
@@ -8,4 +8,21 @@
 
 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.
+ *
+ *  The standard implementation includes nine `AnyVal` subtypes:
+ *
+ *  [[scala.Double]], [[scala.Float]], [[scala.Long]], [[scala.Int]], [[scala.Char]],
+ *  [[scala.Short]], and [[scala.Byte]] are the ''numeric value types''.
+ *
+ *  [[scala.Unit]] and [[scala.Boolean]] are the ''non-numeric value types''.
+ *
+ *  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]].
+ */
 sealed trait AnyVal
diff --git a/src/library/scala/Boolean.scala b/src/library/scala/Boolean.scala
index dc2076cb1d..220fc752c3 100755
--- a/src/library/scala/Boolean.scala
+++ b/src/library/scala/Boolean.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Boolean` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Boolean]] => [[scala.runtime.RichBoolean]]
+ *  which provides useful non-primitive operations.
+ */
 final class Boolean extends AnyVal {
   def unary_! : Boolean = sys.error("stub")
 
@@ -28,7 +32,25 @@ final class Boolean extends AnyVal {
 }
 
 object Boolean extends AnyValCompanion {
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Boolean to be boxed
+   *  @return     a java.lang.Boolean offering `x` as its underlying value.
+   */
+  def box(x: Boolean): java.lang.Boolean = java.lang.Boolean.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Boolean.
+   *
+   *  @param  x   the Boolean to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Boolean
+   *  @return     the Boolean resulting from calling booleanValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Boolean = x.asInstanceOf[java.lang.Boolean].booleanValue()
+
+  /** The String representation of the scala.Boolean companion object.
+   */
   override def toString = "object scala.Boolean"
-  def box(x: Boolean): jl.Boolean = jl.Boolean.valueOf(x)
-  def unbox(x: jl.Object): Boolean = x.asInstanceOf[jl.Boolean].booleanValue()
+
 }
\ No newline at end of file
diff --git a/src/library/scala/Byte.scala b/src/library/scala/Byte.scala
index 69d435b33b..2d27fe37d2 100644
--- a/src/library/scala/Byte.scala
+++ b/src/library/scala/Byte.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Byte` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Byte]] => [[scala.runtime.RichByte]]
+ *  which provides useful non-primitive operations.
+ */
 
 final class Byte extends AnyVal {
   def toByte: Byte = sys.error("stub")
@@ -145,10 +149,32 @@ final class Byte extends AnyVal {
 
 
 object Byte extends AnyValCompanion {
-  final val MinValue = jl.Byte.MIN_VALUE
-  final val MaxValue = jl.Byte.MAX_VALUE
-
-  def box(x: Byte): jl.Byte = jl.Byte.valueOf(x)
-  def unbox(x: jl.Object): Byte = x.asInstanceOf[jl.Byte].byteValue()
+  /** The smallest value representable as a Byte.
+   */
+  final val MinValue = java.lang.Byte.MIN_VALUE
+
+  /** The largest value representable as a Byte.
+   */
+  final val MaxValue = java.lang.Byte.MAX_VALUE
+
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Byte to be boxed
+   *  @return     a java.lang.Byte offering `x` as its underlying value.
+   */
+  def box(x: Byte): java.lang.Byte = java.lang.Byte.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Byte.
+   *
+   *  @param  x   the Byte to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Byte
+   *  @return     the Byte resulting from calling byteValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Byte = x.asInstanceOf[java.lang.Byte].byteValue()
+
+  /** The String representation of the scala.Byte companion object.
+   */
   override def toString = "object scala.Byte"
 }
diff --git a/src/library/scala/Char.scala b/src/library/scala/Char.scala
index 88d7617ea5..b1c9d8e6d4 100644
--- a/src/library/scala/Char.scala
+++ b/src/library/scala/Char.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Char` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Char]] => [[scala.runtime.RichChar]]
+ *  which provides useful non-primitive operations.
+ */
 
 final class Char extends AnyVal {
   def toByte: Byte = sys.error("stub")
@@ -145,10 +149,32 @@ final class Char extends AnyVal {
 
 
 object Char extends AnyValCompanion {
-  final val MinValue = jl.Character.MIN_VALUE
-  final val MaxValue = jl.Character.MAX_VALUE
-
-  def box(x: Char): jl.Character = jl.Character.valueOf(x)
-  def unbox(x: jl.Object): Char = x.asInstanceOf[jl.Character].charValue()
+  /** The smallest value representable as a Char.
+   */
+  final val MinValue = java.lang.Character.MIN_VALUE
+
+  /** The largest value representable as a Char.
+   */
+  final val MaxValue = java.lang.Character.MAX_VALUE
+
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Char to be boxed
+   *  @return     a java.lang.Character offering `x` as its underlying value.
+   */
+  def box(x: Char): java.lang.Character = java.lang.Character.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Character.
+   *
+   *  @param  x   the Char to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Character
+   *  @return     the Char resulting from calling charValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Char = x.asInstanceOf[java.lang.Character].charValue()
+
+  /** The String representation of the scala.Char companion object.
+   */
   override def toString = "object scala.Char"
 }
diff --git a/src/library/scala/Double.scala b/src/library/scala/Double.scala
index fe37860c07..857647b8a5 100644
--- a/src/library/scala/Double.scala
+++ b/src/library/scala/Double.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Double` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Double]] => [[scala.runtime.RichDouble]]
+ *  which provides useful non-primitive operations.
+ */
 
 final class Double extends AnyVal {
   def toByte: Byte = sys.error("stub")
@@ -120,10 +124,10 @@ final class Double extends AnyVal {
 
 object Double extends AnyValCompanion {
   /** The smallest positive value greater than 0.0d.*/
-  final val MinPositiveValue = jl.Double.MIN_VALUE
-  final val NaN              = jl.Double.NaN
-  final val PositiveInfinity = jl.Double.POSITIVE_INFINITY
-  final val NegativeInfinity = jl.Double.NEGATIVE_INFINITY
+  final val MinPositiveValue = java.lang.Double.MIN_VALUE
+  final val NaN              = java.lang.Double.NaN
+  final val PositiveInfinity = java.lang.Double.POSITIVE_INFINITY
+  final val NegativeInfinity = java.lang.Double.NEGATIVE_INFINITY
 
   @deprecated("use Double.MinPositiveValue instead")
   final val Epsilon  = MinPositiveValue
@@ -133,12 +137,29 @@ object Double extends AnyValCompanion {
    *  is the smallest positive value representable by a Double.  In Scala that number
    *  is called Double.MinPositiveValue.
    */
-  final val MinValue = -jl.Double.MAX_VALUE
+  final val MinValue = -java.lang.Double.MAX_VALUE
 
   /** The largest finite positive number representable as a Double. */
-  final val MaxValue = jl.Double.MAX_VALUE
+  final val MaxValue = java.lang.Double.MAX_VALUE
 
-  def box(x: Double): jl.Double = jl.Double.valueOf(x)
-  def unbox(x: jl.Object): Double = x.asInstanceOf[jl.Double].doubleValue()
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Double to be boxed
+   *  @return     a java.lang.Double offering `x` as its underlying value.
+   */
+  def box(x: Double): java.lang.Double = java.lang.Double.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Double.
+   *
+   *  @param  x   the Double to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Double
+   *  @return     the Double resulting from calling doubleValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Double = x.asInstanceOf[java.lang.Double].doubleValue()
+
+  /** The String representation of the scala.Double companion object.
+   */
   override def toString = "object scala.Double"
 }
diff --git a/src/library/scala/Equals.scala b/src/library/scala/Equals.scala
index d0929a9ac4..8aff7af175 100644
--- a/src/library/scala/Equals.scala
+++ b/src/library/scala/Equals.scala
@@ -6,22 +6,22 @@
 **                          |/                                          **
 \*                                                                      */
 
-
-
 package scala
 
 /** An interface containing operations for equality.
  *  The only method not already present in class `AnyRef` is `canEqual`.
  */
 trait Equals {
-
   /** A method that should be called from every well-designed equals method
    *  that is open to be overridden in a subclass. See Programming in Scala,
    *  Chapter 28 for discussion and design.
+   *
+   *  @param    that    the value being probed for possible equality
+   *  @return   true if this instance can possibly equal `that`, otherwise false
    */
   def canEqual(that: Any): Boolean
 
-  /** The equality method defined in `AnyRef`.
+  /** The universal equality method defined in `AnyRef`.
    */
   def equals(that: Any): Boolean
 }
diff --git a/src/library/scala/Float.scala b/src/library/scala/Float.scala
index 39e510e477..59acc73a4d 100644
--- a/src/library/scala/Float.scala
+++ b/src/library/scala/Float.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Float` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Float]] => [[scala.runtime.RichFloat]]
+ *  which provides useful non-primitive operations.
+ */
 
 final class Float extends AnyVal {
   def toByte: Byte = sys.error("stub")
@@ -120,10 +124,10 @@ final class Float extends AnyVal {
 
 object Float extends AnyValCompanion {
   /** The smallest positive value greater than 0.0f.*/
-  final val MinPositiveValue = jl.Float.MIN_VALUE
-  final val NaN              = jl.Float.NaN
-  final val PositiveInfinity = jl.Float.POSITIVE_INFINITY
-  final val NegativeInfinity = jl.Float.NEGATIVE_INFINITY
+  final val MinPositiveValue = java.lang.Float.MIN_VALUE
+  final val NaN              = java.lang.Float.NaN
+  final val PositiveInfinity = java.lang.Float.POSITIVE_INFINITY
+  final val NegativeInfinity = java.lang.Float.NEGATIVE_INFINITY
 
   @deprecated("use Float.MinPositiveValue instead")
   final val Epsilon  = MinPositiveValue
@@ -133,12 +137,29 @@ object Float extends AnyValCompanion {
    *  is the smallest positive value representable by a Float.  In Scala that number
    *  is called Float.MinPositiveValue.
    */
-  final val MinValue = -jl.Float.MAX_VALUE
+  final val MinValue = -java.lang.Float.MAX_VALUE
 
   /** The largest finite positive number representable as a Float. */
-  final val MaxValue = jl.Float.MAX_VALUE
+  final val MaxValue = java.lang.Float.MAX_VALUE
 
-  def box(x: Float): jl.Float = jl.Float.valueOf(x)
-  def unbox(x: jl.Object): Float = x.asInstanceOf[jl.Float].floatValue()
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Float to be boxed
+   *  @return     a java.lang.Float offering `x` as its underlying value.
+   */
+  def box(x: Float): java.lang.Float = java.lang.Float.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Float.
+   *
+   *  @param  x   the Float to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Float
+   *  @return     the Float resulting from calling floatValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Float = x.asInstanceOf[java.lang.Float].floatValue()
+
+  /** The String representation of the scala.Float companion object.
+   */
   override def toString = "object scala.Float"
 }
diff --git a/src/library/scala/Int.scala b/src/library/scala/Int.scala
index 69fb0a66b7..42cb6be44f 100644
--- a/src/library/scala/Int.scala
+++ b/src/library/scala/Int.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Int` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Int]] => [[scala.runtime.RichInt]]
+ *  which provides useful non-primitive operations.
+ */
 
 final class Int extends AnyVal {
   def toByte: Byte = sys.error("stub")
@@ -145,10 +149,32 @@ final class Int extends AnyVal {
 
 
 object Int extends AnyValCompanion {
-  final val MinValue = jl.Integer.MIN_VALUE
-  final val MaxValue = jl.Integer.MAX_VALUE
-
-  def box(x: Int): jl.Integer = jl.Integer.valueOf(x)
-  def unbox(x: jl.Object): Int = x.asInstanceOf[jl.Integer].intValue()
+  /** The smallest value representable as a Int.
+   */
+  final val MinValue = java.lang.Integer.MIN_VALUE
+
+  /** The largest value representable as a Int.
+   */
+  final val MaxValue = java.lang.Integer.MAX_VALUE
+
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Int to be boxed
+   *  @return     a java.lang.Integer offering `x` as its underlying value.
+   */
+  def box(x: Int): java.lang.Integer = java.lang.Integer.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Integer.
+   *
+   *  @param  x   the Int to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Integer
+   *  @return     the Int resulting from calling intValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Int = x.asInstanceOf[java.lang.Integer].intValue()
+
+  /** The String representation of the scala.Int companion object.
+   */
   override def toString = "object scala.Int"
 }
diff --git a/src/library/scala/Long.scala b/src/library/scala/Long.scala
index 7fdefebae3..1de69dab7a 100644
--- a/src/library/scala/Long.scala
+++ b/src/library/scala/Long.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Long` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Long]] => [[scala.runtime.RichLong]]
+ *  which provides useful non-primitive operations.
+ */
 
 final class Long extends AnyVal {
   def toByte: Byte = sys.error("stub")
@@ -145,10 +149,32 @@ final class Long extends AnyVal {
 
 
 object Long extends AnyValCompanion {
-  final val MinValue = jl.Long.MIN_VALUE
-  final val MaxValue = jl.Long.MAX_VALUE
-
-  def box(x: Long): jl.Long = jl.Long.valueOf(x)
-  def unbox(x: jl.Object): Long = x.asInstanceOf[jl.Long].longValue()
+  /** The smallest value representable as a Long.
+   */
+  final val MinValue = java.lang.Long.MIN_VALUE
+
+  /** The largest value representable as a Long.
+   */
+  final val MaxValue = java.lang.Long.MAX_VALUE
+
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Long to be boxed
+   *  @return     a java.lang.Long offering `x` as its underlying value.
+   */
+  def box(x: Long): java.lang.Long = java.lang.Long.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Long.
+   *
+   *  @param  x   the Long to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Long
+   *  @return     the Long resulting from calling longValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Long = x.asInstanceOf[java.lang.Long].longValue()
+
+  /** The String representation of the scala.Long companion object.
+   */
   override def toString = "object scala.Long"
 }
diff --git a/src/library/scala/Product.scala b/src/library/scala/Product.scala
index 786be5ec13..dfa04bbbe7 100644
--- a/src/library/scala/Product.scala
+++ b/src/library/scala/Product.scala
@@ -8,30 +8,33 @@
 
 package scala
 
-/** Base trait for all products.  See [[scala.Product2]].
+/** Base trait for all products, which in the standard library include at least
+ *  [[scala.Product1]] through [[scala.Product22]] and therefore also their
+ *  subclasses [[scala.Tuple1]] through [[scala.Tuple22]].  In addition, all case
+ *  classes implement Product with synthetically generated methods.
  *
  *  @author  Burak Emir
  *  @version 1.0
  *  @since   2.3
  */
 trait Product extends Equals {
-
-  /** Returns the nth element of this product, 0-based.  In other words, for a
-   * product <code>A(x_1,...,x_k)</code>, returns <code>x_(n+1)</code>
-   * where <code>0 &lt;= n &lt; k</code>
+  /** The nth element of this product, 0-based.  In other words, for a
+   *  product `A(x_1, ..., x_k)`, returns x_(n+1) where 0 < n < k.
    *
-   *  @param  n the index of the element to return
-   *  @throws IndexOutOfBoundsException
-   *  @return  The element <code>n</code> elements after the first element
+   *  @param    n   the index of the element to return
+   *  @throws       IndexOutOfBoundsException
+   *  @return       the element `n` elements after the first element
    */
   def productElement(n: Int): Any
 
-  /** Returns the size of this product.
-   * @return For a product <code>A(x_1,...,x_k)</code>, returns `k`
+  /** The size of this product.
+   *  @return     for a product `A(x_1, ..., x_k)`, returns `k`
    */
   def productArity: Int
 
-  /** An iterator that returns all fields of this product */
+  /** An iterator over all the elements of this product.
+   *  @return     in the default implementation, an Iterator[Any]
+   */
   def productIterator: Iterator[Any] = new Iterator[Any] {
     private var c: Int = 0
     private val cmax = productArity
@@ -42,12 +45,11 @@ trait Product extends Equals {
   @deprecated("use productIterator instead")
   def productElements: Iterator[Any] = productIterator
 
-  /**
-   * Returns a string that is used in the `toString` method of subtraits/classes.
-   *  Implementations may override this
-   *  method in order to prepend a string prefix to the result of the
-   *  toString methods.
-   *  @return the empty string
+  /** A string used in the `toString` methods of derived classes.
+   *  Implementations may override this method to prepend a string prefix
+   *  to the result of toString methods.
+   *
+   *  @return   in the default implementation, the empty string
    */
   def productPrefix = ""
 }
diff --git a/src/library/scala/Short.scala b/src/library/scala/Short.scala
index df3e680575..fc9bee32d4 100644
--- a/src/library/scala/Short.scala
+++ b/src/library/scala/Short.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Short` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.Short]] => [[scala.runtime.RichShort]]
+ *  which provides useful non-primitive operations.
+ */
 
 final class Short extends AnyVal {
   def toByte: Byte = sys.error("stub")
@@ -145,10 +149,32 @@ final class Short extends AnyVal {
 
 
 object Short extends AnyValCompanion {
-  final val MinValue = jl.Short.MIN_VALUE
-  final val MaxValue = jl.Short.MAX_VALUE
-
-  def box(x: Short): jl.Short = jl.Short.valueOf(x)
-  def unbox(x: jl.Object): Short = x.asInstanceOf[jl.Short].shortValue()
+  /** The smallest value representable as a Short.
+   */
+  final val MinValue = java.lang.Short.MIN_VALUE
+
+  /** The largest value representable as a Short.
+   */
+  final val MaxValue = java.lang.Short.MAX_VALUE
+
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @param  x   the Short to be boxed
+   *  @return     a java.lang.Short offering `x` as its underlying value.
+   */
+  def box(x: Short): java.lang.Short = java.lang.Short.valueOf(x)
+
+  /** Transform a boxed type into a value type.  Note that this
+   *  method is not typesafe: it accepts any Object, but will throw
+   *  an exception if the argument is not a java.lang.Short.
+   *
+   *  @param  x   the Short to be unboxed.
+   *  @throws     ClassCastException  if the argument is not a java.lang.Short
+   *  @return     the Short resulting from calling shortValue() on `x`
+   */
+  def unbox(x: java.lang.Object): Short = x.asInstanceOf[java.lang.Short].shortValue()
+
+  /** The String representation of the scala.Short companion object.
+   */
   override def toString = "object scala.Short"
 }
diff --git a/src/library/scala/Unit.scala b/src/library/scala/Unit.scala
index 9e2d4dc616..e69f95bf89 100755
--- a/src/library/scala/Unit.scala
+++ b/src/library/scala/Unit.scala
@@ -10,14 +10,16 @@
 
 package scala
 
-import java.{ lang => jl }
-
 import runtime.BoxedUnit
 
+/** Unit is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.  There is
+ *  only one value of type Unit: `()`.
+ */
 final class Unit extends AnyVal { }
 
 object Unit extends AnyValCompanion {
   override def toString = "object scala.Unit"
   def box(x: Unit): BoxedUnit = BoxedUnit.UNIT
-  def unbox(x: jl.Object): Unit = ()
+  def unbox(x: java.lang.Object): Unit = ()
 }
\ No newline at end of file