Merge pull request #2284 from demobox/add-box-unbox-doc-comment

SI-6898 Document AnyVal box and unbox implemention by BoxesRunTime

10 files changed, 59 insertions, 9 deletions

diff --git a/src/compiler/scala/tools/cmd/gen/AnyVals.scala b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
index 35d4eaf1b6..7e01afac2b 100644
--- a/src/compiler/scala/tools/cmd/gen/AnyVals.scala
+++ b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
@@ -22,8 +22,8 @@ trait AnyValReps {
     }
     def coercionCommentExtra = ""
     def coercionComment = """
-  /** Language mandated coercions from @name@ to "wider" types.%s
-   */""".format(coercionCommentExtra)
+/** Language mandated coercions from @name@ to "wider" types.%s
+ */""".format(coercionCommentExtra)
 
     def implicitCoercions: List[String] = {
       val coercions = this match {
@@ -35,7 +35,7 @@ trait AnyValReps {
         case _     => Nil
       }
       if (coercions.isEmpty) Nil
-      else coercionComment :: coercions
+      else coercionComment.lines.toList ++ coercions
     }
 
     def isCardinal: Boolean = isIntegerType(this)
@@ -183,7 +183,7 @@ trait AnyValReps {
     }
     def objectLines = {
       val comp = if (isCardinal) cardinalCompanion else floatingCompanion
-      (comp + allCompanions + "\n" + nonUnitCompanions).trim.lines.toList ++ implicitCoercions map interpolate
+      interpolate(comp + allCompanions + "\n" + nonUnitCompanions).trim.lines.toList ++ (implicitCoercions map interpolate)
     }
 
     /** Makes a set of binary operations based on the given set of ops, args, and resultFn.
@@ -209,11 +209,14 @@ trait AnyValReps {
     )
 
     def lcname = name.toLowerCase
+    def boxedSimpleName = this match {
+      case C => "Character"
+      case I => "Integer"
+      case _ => name
+    }
     def boxedName = this match {
       case U => "scala.runtime.BoxedUnit"
-      case C => "java.lang.Character"
-      case I => "java.lang.Integer"
-      case _ => "java.lang." + name
+      case _ => "java.lang." + boxedSimpleName
     }
     def zeroRep = this match {
       case L => "0L"
@@ -228,7 +231,13 @@ trait AnyValReps {
     def indentN(s: String) = s.lines map indent mkString "\n"
 
     def boxUnboxImpls = 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)
     )
@@ -299,7 +308,7 @@ import scala.language.implicitConversions
 
   def allCompanions = """
 /** Transform a value type into a boxed reference type.
- *
+ *@boxRunTimeDoc@
  *  @param  x   the @name@ to be boxed
  *  @return     a @boxed@ offering `x` as its underlying value.
  */
@@ -308,7 +317,7 @@ def box(x: @name@): @boxed@ = @boxImpl@
 /** Transform a boxed type into a value type.  Note that this
  *  method is not typesafe: it accepts any Object, but will throw
  *  an exception if the argument is not a @boxed@.
- *
+ *@unboxRunTimeDoc@
  *  @param  x   the @boxed@ to be unboxed.
  *  @throws     ClassCastException  if the argument is not a @boxed@
  *  @return     @unboxDoc@
@@ -471,7 +480,9 @@ override def getClass(): Class[Boolean] = null
     def objectLines = interpolate(allCompanions).lines.toList
 
     override def boxUnboxImpls = 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 e43b7d0a82..ddd11257c6 100644
--- a/src/library/scala/Boolean.scala
+++ b/src/library/scala/Boolean.scala
@@ -10,6 +10,8 @@
 
 package scala
 
+import scala.language.implicitConversions
+
 /** `Boolean` (equivalent to Java's `boolean` primitive type) is a
  *  subtype of [[scala.AnyVal]]. Instances of `Boolean` are not
  *  represented by an object in the underlying runtime system.
@@ -114,6 +116,8 @@ object Boolean extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToBoolean`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Boolean to be boxed
    *  @return     a java.lang.Boolean offering `x` as its underlying value.
    */
@@ -123,6 +127,8 @@ object Boolean extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Boolean.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToBoolean`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Boolean to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Boolean
    *  @return     the Boolean resulting from calling booleanValue() on `x`
diff --git a/src/library/scala/Byte.scala b/src/library/scala/Byte.scala
index d1979236d3..2510e859c0 100644
--- a/src/library/scala/Byte.scala
+++ b/src/library/scala/Byte.scala
@@ -606,6 +606,8 @@ object Byte extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToByte`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Byte to be boxed
    *  @return     a java.lang.Byte offering `x` as its underlying value.
    */
@@ -615,6 +617,8 @@ object Byte extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Byte.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToByte`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Byte to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Byte
    *  @return     the Byte resulting from calling byteValue() on `x`
diff --git a/src/library/scala/Char.scala b/src/library/scala/Char.scala
index 00ddff5b3b..1c9a2ba44f 100644
--- a/src/library/scala/Char.scala
+++ b/src/library/scala/Char.scala
@@ -606,6 +606,8 @@ object Char extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToCharacter`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Char to be boxed
    *  @return     a java.lang.Character offering `x` as its underlying value.
    */
@@ -615,6 +617,8 @@ object Char extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Character.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToChar`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Character to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Character
    *  @return     the Char resulting from calling charValue() on `x`
diff --git a/src/library/scala/Double.scala b/src/library/scala/Double.scala
index 85bf9fe5c5..ce081bbec1 100644
--- a/src/library/scala/Double.scala
+++ b/src/library/scala/Double.scala
@@ -10,6 +10,8 @@
 
 package scala
 
+import scala.language.implicitConversions
+
 /** `Double`, a 64-bit IEEE-754 floating point number (equivalent to Java's `double` primitive type) is a
  *  subtype of [[scala.AnyVal]]. Instances of `Double` are not
  *  represented by an object in the underlying runtime system.
@@ -380,6 +382,8 @@ object Double extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToDouble`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Double to be boxed
    *  @return     a java.lang.Double offering `x` as its underlying value.
    */
@@ -389,6 +393,8 @@ object Double extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Double.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToDouble`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Double to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Double
    *  @return     the Double resulting from calling doubleValue() on `x`
diff --git a/src/library/scala/Float.scala b/src/library/scala/Float.scala
index f67f45897f..4ff2d509b8 100644
--- a/src/library/scala/Float.scala
+++ b/src/library/scala/Float.scala
@@ -382,6 +382,8 @@ object Float extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToFloat`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Float to be boxed
    *  @return     a java.lang.Float offering `x` as its underlying value.
    */
@@ -391,6 +393,8 @@ object Float extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Float.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToFloat`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Float to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Float
    *  @return     the Float resulting from calling floatValue() on `x`
diff --git a/src/library/scala/Int.scala b/src/library/scala/Int.scala
index 1bacdbcee9..6a27195b10 100644
--- a/src/library/scala/Int.scala
+++ b/src/library/scala/Int.scala
@@ -606,6 +606,8 @@ object Int extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToInteger`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Int to be boxed
    *  @return     a java.lang.Integer offering `x` as its underlying value.
    */
@@ -615,6 +617,8 @@ object Int extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Integer.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToInt`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Integer to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Integer
    *  @return     the Int resulting from calling intValue() on `x`
diff --git a/src/library/scala/Long.scala b/src/library/scala/Long.scala
index 83adcda819..4d369ae010 100644
--- a/src/library/scala/Long.scala
+++ b/src/library/scala/Long.scala
@@ -606,6 +606,8 @@ object Long extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToLong`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Long to be boxed
    *  @return     a java.lang.Long offering `x` as its underlying value.
    */
@@ -615,6 +617,8 @@ object Long extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Long.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToLong`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Long to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Long
    *  @return     the Long resulting from calling longValue() on `x`
diff --git a/src/library/scala/Short.scala b/src/library/scala/Short.scala
index cdd298e542..4f91c51550 100644
--- a/src/library/scala/Short.scala
+++ b/src/library/scala/Short.scala
@@ -606,6 +606,8 @@ object Short extends AnyValCompanion {
 
   /** Transform a value type into a boxed reference type.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.boxToShort`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the Short to be boxed
    *  @return     a java.lang.Short offering `x` as its underlying value.
    */
@@ -615,6 +617,8 @@ object Short extends AnyValCompanion {
    *  method is not typesafe: it accepts any Object, but will throw
    *  an exception if the argument is not a java.lang.Short.
    *
+   *  Runtime implementation determined by `scala.runtime.BoxesRunTime.unboxToShort`. See [[https://github.com/scala/scala src/library/scala/runtime/BoxesRunTime.java]].
+   *
    *  @param  x   the java.lang.Short to be unboxed.
    *  @throws     ClassCastException  if the argument is not a java.lang.Short
    *  @return     the Short resulting from calling shortValue() on `x`
diff --git a/src/library/scala/Unit.scala b/src/library/scala/Unit.scala
index 01e592ec3c..0e59a184d1 100644
--- a/src/library/scala/Unit.scala
+++ b/src/library/scala/Unit.scala
@@ -10,6 +10,9 @@
 
 package scala
 
+import scala.language.implicitConversions
+
+
 /** `Unit` is a subtype of [[scala.AnyVal]]. There is only one value of type
  *  `Unit`, `()`, and it is not represented by any object in the underlying
  *  runtime system. A method with return type `Unit` is analogous to a Java