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.

10 files changed, 47 insertions, 39 deletions

diff --git a/src/compiler/scala/tools/cmd/gen/AnyVals.scala b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
index e78589908c..0588d2dc77 100644
--- a/src/compiler/scala/tools/cmd/gen/AnyVals.scala
+++ b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
@@ -200,7 +200,8 @@ import scala.language.implicitConversions"""
     def classLines: List[String]
     def objectLines: List[String]
     def commonClassLines = List(
-      "override def getClass(): Class[@name@] = null"
+      "// Provide a more specific return type for Scaladoc",
+      "override def getClass(): Class[@name@] = ???"
     )
 
     def lcname = name.toLowerCase
@@ -225,15 +226,13 @@ import scala.language.implicitConversions"""
     def indent(s: String)  = if (s == "") "" else "  " + s
     def indentN(s: String) = s.lines map indent mkString "\n"
 
-    def boxUnboxImpls = Map(
+    def boxUnboxInterpolations = Map(
       "@boxRunTimeDoc@" -> """
  *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxTo%s`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
  *""".format(boxedSimpleName),
-      "@boxImpl@"   -> "%s.valueOf(x)".format(boxedName),
       "@unboxRunTimeDoc@" -> """
  *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxTo%s`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
  *""".format(name),
-      "@unboxImpl@" -> "x.asInstanceOf[%s].%sValue()".format(boxedName, lcname),
       "@unboxDoc@"  -> "the %s resulting from calling %sValue() on `x`".format(name, lcname)
     )
     def interpolations = Map(
@@ -243,7 +242,7 @@ import scala.language.implicitConversions"""
       "@boxed@"     -> boxedName,
       "@lcname@"    -> lcname,
       "@zero@"      -> zeroRep
-    ) ++ boxUnboxImpls
+    ) ++ boxUnboxInterpolations
 
     def interpolate(s: String): String = interpolations.foldLeft(s) {
       case (str, (key, value)) => str.replaceAll(key, value)
@@ -305,7 +304,7 @@ package scala
  *  @param  x   the @name@ to be boxed
  *  @return     a @boxed@ offering `x` as its underlying value.
  */
-def box(x: @name@): @boxed@ = @boxImpl@
+def box(x: @name@): @boxed@ = ???
 
 /** Transform a boxed type into a value type.  Note that this
  *  method is not typesafe: it accepts any Object, but will throw
@@ -315,7 +314,7 @@ def box(x: @name@): @boxed@ = @boxImpl@
  *  @throws     ClassCastException  if the argument is not a @boxed@
  *  @return     @unboxDoc@
  */
-def unbox(x: java.lang.Object): @name@ = @unboxImpl@
+def unbox(x: java.lang.Object): @name@ = ???
 
 /** The String representation of the scala.@name@ companion object. */
 override def toString = "object scala.@name@"
@@ -444,7 +443,8 @@ def &(x: Boolean): Boolean
   */
 def ^(x: Boolean): Boolean
 
-override def getClass(): Class[Boolean] = null
+// Provide a more specific return type for Scaladoc
+override def getClass(): Class[Boolean] = ???
     """.trim.lines.toList
 
     def objectLines = interpolate(allCompanions + "\n" + nonUnitCompanions).lines.toList
@@ -458,15 +458,14 @@ override def getClass(): Class[Boolean] = null
  */
 """
     def classLines  = List(
-      """override def getClass(): Class[Unit] = null"""
+      "// Provide a more specific return type for Scaladoc",
+      "override def getClass(): Class[Unit] = ???"
     )
     def objectLines = interpolate(allCompanions).lines.toList
 
-    override def boxUnboxImpls = Map(
+    override def boxUnboxInterpolations = Map(
       "@boxRunTimeDoc@" -> "",
-      "@boxImpl@"   -> "scala.runtime.BoxedUnit.UNIT",
       "@unboxRunTimeDoc@" -> "",
-      "@unboxImpl@" -> "()",
       "@unboxDoc@"  -> "the Unit value ()"
     )
   }
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"