Some great AnyVal class hierarchy documentation...

Some great AnyVal class hierarchy documentation from Iain McGinniss. No
Review.

10 files changed, 2862 insertions, 49 deletions

diff --git a/src/compiler/scala/tools/cmd/gen/AnyVals.scala b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
index 3d374b901c..70603bfda6 100644
--- a/src/compiler/scala/tools/cmd/gen/AnyVals.scala
+++ b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
@@ -11,13 +11,113 @@ package gen
 trait AnyValReps {
   self: AnyVals =>
 
-  sealed abstract class AnyValNum(name: String) extends AnyValRep(name) {
+  sealed abstract class AnyValNum(name: String, repr: Option[String], javaEquiv: String) extends AnyValRep(name,repr,javaEquiv) {
+
+    case class Op(val op : String, val doc : String)
+
     def isCardinal: Boolean = isIntegerType(this)
-    def unaryOps            = if (isCardinal) List("+", "-", "~") else List("+", "-")
-    def bitwiseOps          = if (isCardinal) List("|", "&", "^") else Nil
-    def shiftOps            = if (isCardinal) List("<<", ">>>", ">>") else Nil
-    def comparisonOps       = List("==", "!=", "<", "<=", ">", ">=")
-    def otherOps            = List("+", "-" ,"*", "/", "%")
+    def unaryOps = {
+      val ops = List(
+        Op("+", "/**\n" +
+                " * @return this value, unmodified\n" +
+                " */"),
+        Op("-", "/**\n" +
+                " * @return the negation of this value\n" +
+                " */"))
+
+      if(isCardinal)
+        Op("~", "/**\n" +
+                " * @return the bitwise negation of this value\n" +
+                " * @example {{{\n" +
+                " * ~5 == -6\n" +
+                " * // in binary: ~00000101 == \n" +
+                " * //             11111010\n" +
+                " * }}}\n" +
+                " */") :: ops
+      else ops
+    }
+
+    def bitwiseOps =
+      if (isCardinal)
+        List(
+          Op("|", "/**\n" +
+                     "  * @return the bitwise OR of this value and x\n" +
+                     "  * @example {{{\n" +
+                     "  * (0xf0 | 0xaa) == 0xfa\n" +
+                     "  * // in binary:   11110000 \n" +
+                     "  * //            | 10101010 \n" +
+                     "  * //              -------- \n" +
+                     "  * //              11111010\n" +
+                     "  * }}}\n" +
+                     "  */"),
+          Op("&", "/**\n" +
+                     "  * @return the bitwise AND of this value and x\n" +
+                     "  * @example {{{\n" +
+                     "  * (0xf0 & 0xaa) == 0xa0\n" +
+                     "  * // in binary:   11110000 \n" +
+                     "  * //            & 10101010 \n" +
+                     "  * //              -------- \n" +
+                     "  * //              10100000\n" +
+                     "  * }}}\n" +
+                     "  */"),
+          Op("^", "/**\n" +
+                     "  * @return the bitwise XOR of this value and x\n" +
+                     "  * @example {{{\n" +
+                     "  * (0xf0 ^ 0xaa) == 0x5a\n" +
+                     "  * // in binary:   11110000 \n" +
+                     "  * //            ^ 10101010 \n" +
+                     "  * //              -------- \n" +
+                     "  * //              01011010\n" +
+                     "  * }}}\n" +
+                     "  */"))
+      else Nil
+
+    def shiftOps            =
+      if (isCardinal)
+        List(
+          Op("<<",  "/**\n" +
+                       "  * @return this value bit-shifted left by the specified number of bits,\n" +
+                       "  *         filling in the new right bits with zeroes.\n" +
+                       "  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}\n" +
+                       "  */"),
+
+          Op(">>>", "/**\n" +
+                       "  * @return this value bit-shifted right by the specified number of bits,\n" +
+                       "  *         filling the new left bits with zeroes. \n" +
+                       "  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}\n" +
+                       "  * @example {{{\n" +
+                       "  * -21 >>> 3 == 536870909 \n" +
+                       "  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 == \n" +
+                       "  * //            00011111 11111111 11111111 11111101\n" +
+                       "  * }}}\n" +
+                       "  */"),
+
+          Op(">>",  "/**\n" +
+                       "  * @return this value bit-shifted left by the specified number of bits,\n" +
+                       "  *         filling in the right bits with the same value as the left-most bit of this.\n" +
+                       "  *         The effect of this is to retain the sign of the value.\n" +
+                       "  * @example {{{\n" +
+                       "  * -21 >> 3 == -3 \n" +
+                       "  * // in binary: 11111111 11111111 11111111 11101011 >> 3 == \n" +
+                       "  * //            11111111 11111111 11111111 11111101\n" +
+                       "  * }}}\n" +
+                       "  */"))
+      else Nil
+
+    def comparisonOps       = List(
+      Op("==", "/**\n  * @return `true` if this value is equal x, `false` otherwise\n  */"),
+      Op("!=", "/**\n  * @return `true` if this value is not equal to x, `false` otherwise\n  */"),
+      Op("<",  "/**\n  * @return `true` if this value is less than x, `false` otherwise\n  */"),
+      Op("<=", "/**\n  * @return `true` if this value is less than or equal to x, `false` otherwise\n  */"),
+      Op(">",  "/**\n  * @return `true` if this value is greater than x, `false` otherwise\n  */"),
+      Op(">=", "/**\n  * @return `true` if this value is greater than or equal to x, `false` otherwise\n  */"))
+
+    def otherOps = List(
+      Op("+", "/**\n  * @return the sum of this value and x\n  */"),
+      Op("-", "/**\n  * @return the difference of this value and x\n  */"),
+      Op("*", "/**\n  * @return the product of this value and x\n  */"),
+      Op("/", "/**\n  * @return the quotient of this value and x\n  */"),
+      Op("%", "/**\n  * @return the remainder of the division of this value by x\n  */"))
 
     // Given two numeric value types S and T , the operation type of S and T is defined as follows:
     // If both S and T are subrange types then the operation type of S and T is Int.
@@ -33,11 +133,11 @@ trait AnyValReps {
     }
 
     def mkCoercions = numeric map (x => "def to%s: %s".format(x, x))
-    def mkUnaryOps  = unaryOps map (x => "def unary_%s : %s".format(x, this opType I))
+    def mkUnaryOps  = unaryOps map (x => "%s\n  def unary_%s : %s".format(x.doc, x.op, this opType I))
     def mkStringOps = List("def +(x: String): String")
     def mkShiftOps  = (
       for (op <- shiftOps ; arg <- List(I, L)) yield
-        "def %s(x: %s): %s".format(op, arg, this opType I)
+        "%s\n  def %s(x: %s): %s".format(op.doc, op.op, arg, this opType I)
     )
 
     def clumps: List[List[String]] = {
@@ -70,14 +170,15 @@ trait AnyValReps {
      *  @param    resultFn  function which calculates return type based on arg type
      *  @return             list of function definitions
      */
-    def mkBinOpsGroup(ops: List[String], args: List[AnyValNum], resultFn: AnyValNum => AnyValRep): List[String] = (
+    def mkBinOpsGroup(ops: List[Op], args: List[AnyValNum], resultFn: AnyValNum => AnyValRep): List[String] = (
       ops flatMap (op =>
-        args.map(arg => "def %s(x: %s): %s".format(op, arg, resultFn(arg))) :+ ""
+        args.map(arg =>
+          "%s\n  def %s(x: %s): %s".format(op.doc, op.op, arg, resultFn(arg))) :+ ""
       )
     ).toList
   }
 
-  sealed abstract class AnyValRep(val name: String) {
+  sealed abstract class AnyValRep(val name: String, val repr: Option[String], val javaEquiv: String) {
     def classLines: List[String]
     def objectLines: List[String]
     def commonClassLines = List(
@@ -98,6 +199,8 @@ trait AnyValReps {
       case _ => "0"
     }
 
+    def representation = repr.map(", a " + _).getOrElse("")
+
     def indent(s: String)  = if (s == "") "" else "  " + s
     def indentN(s: String) = s.lines map indent mkString "\n"
 
@@ -108,6 +211,8 @@ trait AnyValReps {
     )
     def interpolations = Map(
       "@name@"      -> name,
+      "@representation@" -> representation,
+      "@javaequiv@" -> javaEquiv,
       "@boxed@"     -> boxedName,
       "@lcname@"    -> lcname,
       "@zero@"      -> zeroRep
@@ -156,8 +261,9 @@ package scala
 """.trim.format(timestampString) + "\n\n")
 
   def classDocTemplate = ("""
-/** `@name@` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `@name@`@representation@ (equivalent to Java's `@javaequiv@` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `@name@` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.@name@]] => [[scala.runtime.Rich@name@]]
  *  which provides useful non-primitive operations.
@@ -225,14 +331,14 @@ final val MaxValue = @boxed@.MAX_VALUE
 }
 
 class AnyVals extends AnyValReps with AnyValTemplates {
-  object B extends AnyValNum("Byte")
-  object S extends AnyValNum("Short")
-  object C extends AnyValNum("Char")
-  object I extends AnyValNum("Int")
-  object L extends AnyValNum("Long")
-  object F extends AnyValNum("Float")
-  object D extends AnyValNum("Double")
-  object Z extends AnyValRep("Boolean") {
+  object B extends AnyValNum("Byte",    Some("8-bit signed integer"),                  "byte")
+  object S extends AnyValNum("Short",   Some("16-bit signed integer"),                 "short")
+  object C extends AnyValNum("Char",    Some("16-bit unsigned integer"),               "char")
+  object I extends AnyValNum("Int",     Some("32-bit signed integer"),                 "int")
+  object L extends AnyValNum("Long",    Some("64-bit signed integer"),                 "long")
+  object F extends AnyValNum("Float",   Some("32-bit IEEE-754 floating point number"), "float")
+  object D extends AnyValNum("Double",  Some("64-bit IEEE-754 floating point number"), "double")
+  object Z extends AnyValRep("Boolean", None,                                          "boolean") {
     def classLines = """
 /**
  * Negates a Boolean expression.
@@ -328,11 +434,11 @@ def getClass(): Class[Boolean] = sys.error("stub")
 
     def objectLines = interpolate(allCompanions).lines.toList
   }
-  object U extends AnyValRep("Unit") {
+  object U extends AnyValRep("Unit", None, "void") {
     override def classDoc = """
-/** 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: `()`.
+/** `Unit` (equivalent to Java's `void` type) is a subtype of [[scala.AnyVal]], meaning that
+ *  it is not represented by an object in the underlying runtime system. There is
+ *  only one value of type `Unit`: `()`.
  */
 """
     def classLines  = List(
diff --git a/src/library/scala/Boolean.scala b/src/library/scala/Boolean.scala
index dd5439d537..be96377a21 100755
--- a/src/library/scala/Boolean.scala
+++ b/src/library/scala/Boolean.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Boolean` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Boolean` (equivalent to Java's `boolean` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Boolean` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Boolean]] => [[scala.runtime.RichBoolean]]
  *  which provides useful non-primitive operations.
diff --git a/src/library/scala/Byte.scala b/src/library/scala/Byte.scala
index 8c598e044a..b9e36b0136 100644
--- a/src/library/scala/Byte.scala
+++ b/src/library/scala/Byte.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Byte` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Byte`, a 8-bit signed integer (equivalent to Java's `byte` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Byte` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Byte]] => [[scala.runtime.RichByte]]
  *  which provides useful non-primitive operations.
@@ -25,123 +26,568 @@ final class Byte extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return the bitwise negation of this value
+ * @example {{{
+ * ~5 == -6
+ * // in binary: ~00000101 ==
+ * //             11111010
+ * }}}
+ */
+  def unary_~ : Int = sys.error("stub")
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Int = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Int = sys.error("stub")
-  def unary_~ : Int = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Long): Int = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Byte] = sys.error("stub")
diff --git a/src/library/scala/Char.scala b/src/library/scala/Char.scala
index a8f15125bf..4bbf02a215 100644
--- a/src/library/scala/Char.scala
+++ b/src/library/scala/Char.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Char` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Char`, a 16-bit unsigned integer (equivalent to Java's `char` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Char` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Char]] => [[scala.runtime.RichChar]]
  *  which provides useful non-primitive operations.
@@ -25,123 +26,568 @@ final class Char extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return the bitwise negation of this value
+ * @example {{{
+ * ~5 == -6
+ * // in binary: ~00000101 ==
+ * //             11111010
+ * }}}
+ */
+  def unary_~ : Int = sys.error("stub")
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Int = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Int = sys.error("stub")
-  def unary_~ : Int = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Long): Int = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Char] = sys.error("stub")
diff --git a/src/library/scala/Double.scala b/src/library/scala/Double.scala
index 108c6207bb..b4bb9f0432 100644
--- a/src/library/scala/Double.scala
+++ b/src/library/scala/Double.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Double` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Double`, a 64-bit IEEE-754 floating point number (equivalent to Java's `double` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Double` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Double]] => [[scala.runtime.RichDouble]]
  *  which provides useful non-primitive operations.
@@ -25,97 +26,334 @@ final class Double extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Double = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Double = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Double = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Double = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Double = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Double = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Double = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Double = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Double = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Double = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Double = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Double = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Double = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Double = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Double = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Double = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Double = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Double = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Double = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Double = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Double = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Double = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Double = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Double = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Double = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Double = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Double = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Double = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Double = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Double = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Double = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Double = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Double] = sys.error("stub")
diff --git a/src/library/scala/Float.scala b/src/library/scala/Float.scala
index 9ef7181806..ed61168e90 100644
--- a/src/library/scala/Float.scala
+++ b/src/library/scala/Float.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Float` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Float`, a 32-bit IEEE-754 floating point number (equivalent to Java's `float` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Float` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Float]] => [[scala.runtime.RichFloat]]
  *  which provides useful non-primitive operations.
@@ -25,97 +26,334 @@ final class Float extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Float = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Float = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Float] = sys.error("stub")
diff --git a/src/library/scala/Int.scala b/src/library/scala/Int.scala
index 4546934149..8ad678acfe 100644
--- a/src/library/scala/Int.scala
+++ b/src/library/scala/Int.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Int` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Int`, a 32-bit signed integer (equivalent to Java's `int` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Int` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Int]] => [[scala.runtime.RichInt]]
  *  which provides useful non-primitive operations.
@@ -25,123 +26,568 @@ final class Int extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return the bitwise negation of this value
+ * @example {{{
+ * ~5 == -6
+ * // in binary: ~00000101 ==
+ * //             11111010
+ * }}}
+ */
+  def unary_~ : Int = sys.error("stub")
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Int = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Int = sys.error("stub")
-  def unary_~ : Int = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Long): Int = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Int] = sys.error("stub")
diff --git a/src/library/scala/Long.scala b/src/library/scala/Long.scala
index 12b8a25b8a..2a2bc896ac 100644
--- a/src/library/scala/Long.scala
+++ b/src/library/scala/Long.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Long` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Long`, a 64-bit signed integer (equivalent to Java's `long` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Long` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Long]] => [[scala.runtime.RichLong]]
  *  which provides useful non-primitive operations.
@@ -25,123 +26,568 @@ final class Long extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return the bitwise negation of this value
+ * @example {{{
+ * ~5 == -6
+ * // in binary: ~00000101 ==
+ * //             11111010
+ * }}}
+ */
+  def unary_~ : Long = sys.error("stub")
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Long = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Long = sys.error("stub")
-  def unary_~ : Long = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Int): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Long): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Int): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Long): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Int): Long = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Short): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Char): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Int): Long = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Short): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Char): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Int): Long = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Short): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Char): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Int): Long = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Long] = sys.error("stub")
diff --git a/src/library/scala/Short.scala b/src/library/scala/Short.scala
index 81953505b7..0cba03db37 100644
--- a/src/library/scala/Short.scala
+++ b/src/library/scala/Short.scala
@@ -10,8 +10,9 @@
 
 package scala
 
-/** `Short` is a member of the value classes, those whose instances are
- *  not represented as objects by the underlying host system.
+/** `Short`, a 16-bit signed integer (equivalent to Java's `short` primitive type) is a
+ *  subtype of [[scala.AnyVal]], meaning that instances of `Short` are not
+ *  represented by an object in the underlying runtime system.
  *
  *  There is an implicit conversion from [[scala.Short]] => [[scala.runtime.RichShort]]
  *  which provides useful non-primitive operations.
@@ -25,123 +26,568 @@ final class Short extends AnyVal {
   def toFloat: Float = sys.error("stub")
   def toDouble: Double = sys.error("stub")
 
+  /**
+ * @return the bitwise negation of this value
+ * @example {{{
+ * ~5 == -6
+ * // in binary: ~00000101 ==
+ * //             11111010
+ * }}}
+ */
+  def unary_~ : Int = sys.error("stub")
+  /**
+ * @return this value, unmodified
+ */
   def unary_+ : Int = sys.error("stub")
+  /**
+ * @return the negation of this value
+ */
   def unary_- : Int = sys.error("stub")
-  def unary_~ : Int = sys.error("stub")
 
   def +(x: String): String = sys.error("stub")
 
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the new right bits with zeroes.
+  * @example {{{ 6 << 3 == 48 // in binary: 0110 << 3 == 0110000 }}}
+  */
   def <<(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted right by the specified number of bits,
+  *         filling the new left bits with zeroes.
+  * @example {{{ 21 >>> 3 == 2 // in binary: 010101 >>> 3 == 010 }}}
+  * @example {{{
+  * -21 >>> 3 == 536870909
+  * // in binary: 11111111 11111111 11111111 11101011 >>> 3 ==
+  * //            00011111 11111111 11111111 11111101
+  * }}}
+  */
   def >>>(x: Long): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Int): Int = sys.error("stub")
+  /**
+  * @return this value bit-shifted left by the specified number of bits,
+  *         filling in the right bits with the same value as the left-most bit of this.
+  *         The effect of this is to retain the sign of the value.
+  * @example {{{
+  * -21 >> 3 == -3
+  * // in binary: 11111111 11111111 11111111 11101011 >> 3 ==
+  * //            11111111 11111111 11111111 11111101
+  * }}}
+  */
   def >>(x: Long): Int = sys.error("stub")
 
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is equal x, `false` otherwise
+  */
   def ==(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is not equal to x, `false` otherwise
+  */
   def !=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than x, `false` otherwise
+  */
   def <(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is less than or equal to x, `false` otherwise
+  */
   def <=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than x, `false` otherwise
+  */
   def >(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Byte): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Short): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Char): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Int): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Long): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Float): Boolean = sys.error("stub")
+  /**
+  * @return `true` if this value is greater than or equal to x, `false` otherwise
+  */
   def >=(x: Double): Boolean = sys.error("stub")
 
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise OR of this value and x
+  * @example {{{
+  * (0xf0 | 0xaa) == 0xfa
+  * // in binary:   11110000
+  * //            | 10101010
+  * //              --------
+  * //              11111010
+  * }}}
+  */
   def |(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise AND of this value and x
+  * @example {{{
+  * (0xf0 & 0xaa) == 0xa0
+  * // in binary:   11110000
+  * //            & 10101010
+  * //              --------
+  * //              10100000
+  * }}}
+  */
   def &(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Short): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Char): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Int): Int = sys.error("stub")
+  /**
+  * @return the bitwise XOR of this value and x
+  * @example {{{
+  * (0xf0 ^ 0xaa) == 0x5a
+  * // in binary:   11110000
+  * //            ^ 10101010
+  * //              --------
+  * //              01011010
+  * }}}
+  */
   def ^(x: Long): Long = sys.error("stub")
 
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Short): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Char): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Int): Int = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Long): Long = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Float): Float = sys.error("stub")
+  /**
+  * @return the sum of this value and x
+  */
   def +(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Short): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Char): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Int): Int = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Long): Long = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Float): Float = sys.error("stub")
+  /**
+  * @return the difference of this value and x
+  */
   def -(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Short): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Char): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Int): Int = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Long): Long = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Float): Float = sys.error("stub")
+  /**
+  * @return the product of this value and x
+  */
   def *(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Short): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Char): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Int): Int = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Long): Long = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Float): Float = sys.error("stub")
+  /**
+  * @return the quotient of this value and x
+  */
   def /(x: Double): Double = sys.error("stub")
 
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Byte): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Short): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Char): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Int): Int = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Long): Long = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Float): Float = sys.error("stub")
+  /**
+  * @return the remainder of the division of this value by x
+  */
   def %(x: Double): Double = sys.error("stub")
 
   def getClass(): Class[Short] = sys.error("stub")
diff --git a/src/library/scala/Unit.scala b/src/library/scala/Unit.scala
index c5d12afeba..0059ded33a 100755
--- a/src/library/scala/Unit.scala
+++ b/src/library/scala/Unit.scala
@@ -11,9 +11,9 @@
 package scala
 
 
-/** 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: `()`.
+/** `Unit` (equivalent to Java's `void` type) is a subtype of [[scala.AnyVal]], meaning that
+ *  it is not represented by an object in the underlying runtime system. There is
+ *  only one value of type `Unit`: `()`.
  */
 final class Unit extends AnyVal {
   def getClass(): Class[Unit] = sys.error("stub")