SI-6710 Clarify stub methods in primitive value classes

- Replaces the implementations of box/unbox in AnyVal companions by
  `???`, the methods are only stubs, and the impls did not correspond
  to the actual behavior. The doc comment already points to the actual
  implementation in BoxesRunTime.
- Replaces the body of `getClass` from `null` to `???` and clarifies in
  a comment why the overrides exist.

9 files changed, 36 insertions, 27 deletions

diff --git a/src/library/scala/Boolean.scala b/src/library/scala/Boolean.scala
index 53b4fb2af2..60fb594ecc 100644
--- a/src/library/scala/Boolean.scala
+++ b/src/library/scala/Boolean.scala
@@ -102,7 +102,8 @@ final abstract class Boolean private extends AnyVal {
     */
   def ^(x: Boolean): Boolean
 
-  override def getClass(): Class[Boolean] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Boolean] = ???
 }
 
 object Boolean extends AnyValCompanion {
@@ -114,7 +115,7 @@ object Boolean extends AnyValCompanion {
    *  @param  x   the Boolean to be boxed
    *  @return     a java.lang.Boolean offering `x` as its underlying value.
    */
-  def box(x: Boolean): java.lang.Boolean = java.lang.Boolean.valueOf(x)
+  def box(x: Boolean): java.lang.Boolean = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -126,7 +127,7 @@ object Boolean extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Boolean
    *  @return     the Boolean resulting from calling booleanValue() on `x`
    */
-  def unbox(x: java.lang.Object): Boolean = x.asInstanceOf[java.lang.Boolean].booleanValue()
+  def unbox(x: java.lang.Object): Boolean = ???
 
   /** The String representation of the scala.Boolean companion object. */
   override def toString = "object scala.Boolean"
diff --git a/src/library/scala/Byte.scala b/src/library/scala/Byte.scala
index fb662911b3..c0b376ee70 100644
--- a/src/library/scala/Byte.scala
+++ b/src/library/scala/Byte.scala
@@ -434,7 +434,8 @@ final abstract class Byte private extends AnyVal {
   /** Returns the remainder of the division of this value by `x`. */
   def %(x: Double): Double
 
-  override def getClass(): Class[Byte] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Byte] = ???
 }
 
 object Byte extends AnyValCompanion {
@@ -451,7 +452,7 @@ object Byte extends AnyValCompanion {
    *  @param  x   the Byte to be boxed
    *  @return     a java.lang.Byte offering `x` as its underlying value.
    */
-  def box(x: Byte): java.lang.Byte = java.lang.Byte.valueOf(x)
+  def box(x: Byte): java.lang.Byte = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -463,7 +464,7 @@ object Byte extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Byte
    *  @return     the Byte resulting from calling byteValue() on `x`
    */
-  def unbox(x: java.lang.Object): Byte = x.asInstanceOf[java.lang.Byte].byteValue()
+  def unbox(x: java.lang.Object): Byte = ???
 
   /** The String representation of the scala.Byte companion object. */
   override def toString = "object scala.Byte"
diff --git a/src/library/scala/Char.scala b/src/library/scala/Char.scala
index 9f06503569..0abf68f117 100644
--- a/src/library/scala/Char.scala
+++ b/src/library/scala/Char.scala
@@ -434,7 +434,8 @@ final abstract class Char private extends AnyVal {
   /** Returns the remainder of the division of this value by `x`. */
   def %(x: Double): Double
 
-  override def getClass(): Class[Char] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Char] = ???
 }
 
 object Char extends AnyValCompanion {
@@ -451,7 +452,7 @@ object Char extends AnyValCompanion {
    *  @param  x   the Char to be boxed
    *  @return     a java.lang.Character offering `x` as its underlying value.
    */
-  def box(x: Char): java.lang.Character = java.lang.Character.valueOf(x)
+  def box(x: Char): java.lang.Character = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -463,7 +464,7 @@ object Char extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Character
    *  @return     the Char resulting from calling charValue() on `x`
    */
-  def unbox(x: java.lang.Object): Char = x.asInstanceOf[java.lang.Character].charValue()
+  def unbox(x: java.lang.Object): Char = ???
 
   /** The String representation of the scala.Char companion object. */
   override def toString = "object scala.Char"
diff --git a/src/library/scala/Double.scala b/src/library/scala/Double.scala
index a58fa3ed25..9b2cca2cbc 100644
--- a/src/library/scala/Double.scala
+++ b/src/library/scala/Double.scala
@@ -200,7 +200,8 @@ final abstract class Double private extends AnyVal {
   /** Returns the remainder of the division of this value by `x`. */
   def %(x: Double): Double
 
-  override def getClass(): Class[Double] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Double] = ???
 }
 
 object Double extends AnyValCompanion {
@@ -229,7 +230,7 @@ object Double extends AnyValCompanion {
    *  @param  x   the Double to be boxed
    *  @return     a java.lang.Double offering `x` as its underlying value.
    */
-  def box(x: Double): java.lang.Double = java.lang.Double.valueOf(x)
+  def box(x: Double): java.lang.Double = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -241,7 +242,7 @@ object Double extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Double
    *  @return     the Double resulting from calling doubleValue() on `x`
    */
-  def unbox(x: java.lang.Object): Double = x.asInstanceOf[java.lang.Double].doubleValue()
+  def unbox(x: java.lang.Object): Double = ???
 
   /** The String representation of the scala.Double companion object. */
   override def toString = "object scala.Double"
diff --git a/src/library/scala/Float.scala b/src/library/scala/Float.scala
index 3c59057a8d..8933ff1257 100644
--- a/src/library/scala/Float.scala
+++ b/src/library/scala/Float.scala
@@ -200,7 +200,8 @@ final abstract class Float private extends AnyVal {
   /** Returns the remainder of the division of this value by `x`. */
   def %(x: Double): Double
 
-  override def getClass(): Class[Float] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Float] = ???
 }
 
 object Float extends AnyValCompanion {
@@ -229,7 +230,7 @@ object Float extends AnyValCompanion {
    *  @param  x   the Float to be boxed
    *  @return     a java.lang.Float offering `x` as its underlying value.
    */
-  def box(x: Float): java.lang.Float = java.lang.Float.valueOf(x)
+  def box(x: Float): java.lang.Float = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -241,7 +242,7 @@ object Float extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Float
    *  @return     the Float resulting from calling floatValue() on `x`
    */
-  def unbox(x: java.lang.Object): Float = x.asInstanceOf[java.lang.Float].floatValue()
+  def unbox(x: java.lang.Object): Float = ???
 
   /** The String representation of the scala.Float companion object. */
   override def toString = "object scala.Float"
diff --git a/src/library/scala/Int.scala b/src/library/scala/Int.scala
index 3bd3775eba..77c026f0cc 100644
--- a/src/library/scala/Int.scala
+++ b/src/library/scala/Int.scala
@@ -434,7 +434,8 @@ final abstract class Int private extends AnyVal {
   /** Returns the remainder of the division of this value by `x`. */
   def %(x: Double): Double
 
-  override def getClass(): Class[Int] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Int] = ???
 }
 
 object Int extends AnyValCompanion {
@@ -451,7 +452,7 @@ object Int extends AnyValCompanion {
    *  @param  x   the Int to be boxed
    *  @return     a java.lang.Integer offering `x` as its underlying value.
    */
-  def box(x: Int): java.lang.Integer = java.lang.Integer.valueOf(x)
+  def box(x: Int): java.lang.Integer = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -463,7 +464,7 @@ object Int extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Integer
    *  @return     the Int resulting from calling intValue() on `x`
    */
-  def unbox(x: java.lang.Object): Int = x.asInstanceOf[java.lang.Integer].intValue()
+  def unbox(x: java.lang.Object): Int = ???
 
   /** The String representation of the scala.Int companion object. */
   override def toString = "object scala.Int"
diff --git a/src/library/scala/Long.scala b/src/library/scala/Long.scala
index b27a66647f..1d219ecf1e 100644
--- a/src/library/scala/Long.scala
+++ b/src/library/scala/Long.scala
@@ -434,7 +434,8 @@ final abstract class Long private extends AnyVal {
   /** Returns the remainder of the division of this value by `x`. */
   def %(x: Double): Double
 
-  override def getClass(): Class[Long] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Long] = ???
 }
 
 object Long extends AnyValCompanion {
@@ -451,7 +452,7 @@ object Long extends AnyValCompanion {
    *  @param  x   the Long to be boxed
    *  @return     a java.lang.Long offering `x` as its underlying value.
    */
-  def box(x: Long): java.lang.Long = java.lang.Long.valueOf(x)
+  def box(x: Long): java.lang.Long = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -463,7 +464,7 @@ object Long extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Long
    *  @return     the Long resulting from calling longValue() on `x`
    */
-  def unbox(x: java.lang.Object): Long = x.asInstanceOf[java.lang.Long].longValue()
+  def unbox(x: java.lang.Object): Long = ???
 
   /** The String representation of the scala.Long companion object. */
   override def toString = "object scala.Long"
diff --git a/src/library/scala/Short.scala b/src/library/scala/Short.scala
index 2cbbf3cc59..8bfe6f935f 100644
--- a/src/library/scala/Short.scala
+++ b/src/library/scala/Short.scala
@@ -434,7 +434,8 @@ final abstract class Short private extends AnyVal {
   /** Returns the remainder of the division of this value by `x`. */
   def %(x: Double): Double
 
-  override def getClass(): Class[Short] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Short] = ???
 }
 
 object Short extends AnyValCompanion {
@@ -451,7 +452,7 @@ object Short extends AnyValCompanion {
    *  @param  x   the Short to be boxed
    *  @return     a java.lang.Short offering `x` as its underlying value.
    */
-  def box(x: Short): java.lang.Short = java.lang.Short.valueOf(x)
+  def box(x: Short): java.lang.Short = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -463,7 +464,7 @@ object Short extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a java.lang.Short
    *  @return     the Short resulting from calling shortValue() on `x`
    */
-  def unbox(x: java.lang.Object): Short = x.asInstanceOf[java.lang.Short].shortValue()
+  def unbox(x: java.lang.Object): Short = ???
 
   /** The String representation of the scala.Short companion object. */
   override def toString = "object scala.Short"
diff --git a/src/library/scala/Unit.scala b/src/library/scala/Unit.scala
index 018ad24a99..873281bb8f 100644
--- a/src/library/scala/Unit.scala
+++ b/src/library/scala/Unit.scala
@@ -19,7 +19,8 @@ package scala
  *  method which is declared `void`.
  */
 final abstract class Unit private extends AnyVal {
-  override def getClass(): Class[Unit] = null
+  // Provide a more specific return type for Scaladoc
+  override def getClass(): Class[Unit] = ???
 }
 
 object Unit extends AnyValCompanion {
@@ -29,7 +30,7 @@ object Unit extends AnyValCompanion {
    *  @param  x   the Unit to be boxed
    *  @return     a scala.runtime.BoxedUnit offering `x` as its underlying value.
    */
-  def box(x: Unit): scala.runtime.BoxedUnit = scala.runtime.BoxedUnit.UNIT
+  def box(x: Unit): scala.runtime.BoxedUnit = ???
 
   /** Transform a boxed type into a value type.  Note that this
    *  method is not typesafe: it accepts any Object, but will throw
@@ -39,7 +40,7 @@ object Unit extends AnyValCompanion {
    *  @throws     ClassCastException  if the argument is not a scala.runtime.BoxedUnit
    *  @return     the Unit value ()
    */
-  def unbox(x: java.lang.Object): Unit = ()
+  def unbox(x: java.lang.Object): Unit = ???
 
   /** The String representation of the scala.Unit companion object. */
   override def toString = "object scala.Unit"