Working on the documentation of core classes.

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

2 files changed, 103 insertions, 78 deletions

diff --git a/src/compiler/scala/tools/cmd/gen/AnyVals.scala b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
index f6f48359cd..db07229ce9 100644
--- a/src/compiler/scala/tools/cmd/gen/AnyVals.scala
+++ b/src/compiler/scala/tools/cmd/gen/AnyVals.scala
@@ -7,8 +7,20 @@ package scala.tools.cmd
 package gen
 
 trait AnyValTemplates {
+  def indent(s: String) = if (s == "") "" else "  " + s
+  def indentN(s: String) = s.lines map indent mkString "\n"
+
+def classDocTemplate = ("""
+/** `@name@` is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.
+ *
+ *  There is an implicit conversion from [[scala.@name@]] => [[scala.runtime.Rich@name@]]
+ *  which provides useful non-primitive operations.
+ */
+""".trim + "\n")
+
   def timestampString = ""
-  def template = ("""
+  def headerTemplate = ("""
 /*                     __                                               *\
 **     ________ ___   / /  ___     Scala API                            **
 **    / __/ __// _ | / /  / _ |    (c) 2002-2011, LAMP/EPFL             **
@@ -20,11 +32,32 @@ trait AnyValTemplates {
 %s
 package scala
 
-import java.{ lang => jl }
-  """.trim.format(timestampString) + "\n\n"
-  )
+""".trim.format(timestampString) + "\n\n")
+
+  def nonUnitCompanion = """
+/** Transform a value type into a boxed reference type.
+ *
+ *  @param  x   the @name@ to be boxed
+ *  @return     a @type@ offering `x` as its underlying value.
+ */
+def box(x: @name@): @type@ = @type@.valueOf(x)
+
+/** Transform a boxed type into a value type.  Note that this
+ *  method is not typesafe: it accepts any Object, but will throw
+ *  an exception if the argument is not a @type@.
+ *
+ *  @param  x   the @name@ to be unboxed.
+ *  @throws     ClassCastException  if the argument is not a @type@
+ *  @return     the @name@ resulting from calling @lcname@Value() on `x`
+ */
+def unbox(x: java.lang.Object): @name@ = x.asInstanceOf[@type@].@lcname@Value()
 
-  def booleanBody = """
+/** The String representation of the scala.@name@ companion object.
+ */
+override def toString = "object scala.@name@"
+  """
+
+  def booleanBody = ("""
 final class Boolean extends AnyVal {
   def unary_! : Boolean = sys.error("stub")
 
@@ -41,34 +74,35 @@ final class Boolean extends AnyVal {
 }
 
 object Boolean extends AnyValCompanion {
-  override def toString = "object scala.Boolean"
-  def box(x: Boolean): jl.Boolean = jl.Boolean.valueOf(x)
-  def unbox(x: jl.Object): Boolean = x.asInstanceOf[jl.Boolean].booleanValue()
-}
-  """.trim
+""".trim + indentN(nonUnitCompanion) + "\n}")
 
   def unitBody = """
 import runtime.BoxedUnit
 
+/** Unit is a member of the value classes, those whose instances are
+ *  not represented as objects by the underlying host system.  There is
+ *  only one value of type Unit: `()`.
+ */
 final class Unit extends AnyVal { }
 
 object Unit extends AnyValCompanion {
   override def toString = "object scala.Unit"
   def box(x: Unit): BoxedUnit = BoxedUnit.UNIT
-  def unbox(x: jl.Object): Unit = ()
+  def unbox(x: java.lang.Object): Unit = ()
 }
   """.trim
 
-  def cardinalCompanion = """
+  def cardinalCompanion = ("""
+/** The smallest value representable as a @name@.
+ */
 final val MinValue = @type@.MIN_VALUE
-final val MaxValue = @type@.MAX_VALUE
 
-def box(x: @name@): @type@ = @type@.valueOf(x)
-def unbox(x: jl.Object): @name@ = x.asInstanceOf[@type@].@lcname@Value()
-override def toString = "object scala.@name@"
-  """.trim.lines
+/** The largest value representable as a @name@.
+ */
+final val MaxValue = @type@.MAX_VALUE
+""" + nonUnitCompanion).trim.lines
 
-  def floatingCompanion = """
+  def floatingCompanion = ("""
 /** The smallest positive value greater than @zero@.*/
 final val MinPositiveValue = @type@.MIN_VALUE
 final val NaN              = @type@.NaN
@@ -87,14 +121,32 @@ final val MinValue = -@type@.MAX_VALUE
 
 /** The largest finite positive number representable as a @name@. */
 final val MaxValue = @type@.MAX_VALUE
-
-def box(x: @name@): @type@ = @type@.valueOf(x)
-def unbox(x: jl.Object): @name@ = x.asInstanceOf[@type@].@lcname@Value()
-override def toString = "object scala.@name@"
-  """.trim.lines
+""" + nonUnitCompanion).trim.lines
 }
 
 class AnyVals extends AnyValTemplates {
+  trait AnyValInterpolation {
+    def name: String
+    def isCardinal: Boolean
+    def restype: String
+    def tpe: String
+    def zero: String
+
+    lazy val interpolations = Map(
+      "@restype@"  -> restype,
+      "@name@"     -> name,
+      "@type@"     -> tpe,
+      "@lcname@"   -> name.toLowerCase,
+      "@zero@"     -> zero
+    )
+    def interpolate(s: String): String = interpolations.foldLeft(s) {
+      case (str, (key, value)) => str.replaceAll(key, value)
+    }
+
+    def classDoc = interpolate(classDocTemplate)
+    def make(): String
+  }
+
   val B = "Byte"
   val S = "Short"
   val C = "Char"
@@ -107,19 +159,38 @@ class AnyVals extends AnyValTemplates {
   lazy val floating = List(F, D)
   lazy val numeric  = cardinal ++ floating
 
-  def javaType(primType: String) = "jl." + (primType match {
+  def javaType(primType: String) = "java.lang." + (primType match {
     case C => "Character"
     case I => "Integer"
     case t => t
   })
 
-  def make() =
-    (numeric zip (numeric map (name => new AnyValOps(name).make()))) ++ List(
-      ("Boolean", template + booleanBody),
-      ("Unit", template + unitBody)
-    )
+  def make() = {
+    val nums = numeric map (name => new AnyValOps(name).make())
+    (numeric zip nums) :+ ("Boolean", makeBoolean()) :+ ("Unit", makeUnit())
+  }
+
+  def makeBoolean() = (new AnyValInterpolation {
+    def name       = "Boolean"
+    def isCardinal = false
+    def restype    = "Nothing"
+    def tpe        = "java.lang.Boolean"
+    def zero       = "false"
+
+    def make() = headerTemplate + classDoc + interpolate(booleanBody)
+  }).make()
+
+  def makeUnit() = (new AnyValInterpolation {
+    def name       = "Unit"
+    def isCardinal = false
+    def restype    = "Nothing"
+    def tpe        = "scala.runtime.BoxedUnit"
+    def zero       = "()"
 
-  class AnyValOps(name: String) {
+    def make() = headerTemplate + unitBody
+  }).make()
+
+  class AnyValOps(val name: String) extends AnyValInterpolation {
     val isCardinal = cardinal contains name
     val restype    = if ("LFD" contains name.head) name else I
     val tpe        = javaType(name)
@@ -129,14 +200,6 @@ class AnyVals extends AnyValTemplates {
       case 'D' => "0.0d"
       case _   => "0"
     }
-    val interpolations = Map(
-      "@restype@"  -> restype,
-      "@name@"     -> name,
-      "@type@"     -> tpe,
-      "@lcname@"   -> name.toLowerCase,
-      "@zero@"     -> zero
-    )
-
     def mkCoercions = numeric map (x => "def to%s: %s".format(x, x))
     def mkUnaryOps  = unaryops map (op => "def unary_%s : @restype@".format(op))
     def mkCommon    = List(
@@ -158,7 +221,6 @@ class AnyVals extends AnyValTemplates {
     }
 
     def defImplementation = "sys.error(\"stub\")"
-    def indent(s: String) = if (s == "") "" else "  " + s
     def mkClass = {
       val lines = clumps.foldLeft(List[String]()) {
         case (res, Nil)   => res
@@ -169,7 +231,7 @@ class AnyVals extends AnyValTemplates {
           }
           res ++ xs
       }
-      assemble("final class", "AnyVal", lines)
+      classDoc + assemble("final class", "AnyVal", lines)
     }
     def mkObject = assemble("object", "AnyValCompanion", companionBody map interpolate toList)
 
@@ -179,11 +241,7 @@ class AnyVals extends AnyValTemplates {
       "}"
     ).mkString("\n", "\n", "\n")
 
-    def make() = template + mkClass + "\n" + mkObject
-
-    def interpolate(s: String): String = interpolations.foldLeft(s) {
-      case (str, (key, value)) => str.replaceAll(key, value)
-    }
+    def make() = headerTemplate + mkClass + "\n" + mkObject
 
     /** Makes a set of binary operations based on the given set of ops, args, and resultFn.
      *
diff --git a/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
index 6ce2feea84..6b6886a599 100644
--- a/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
+++ b/src/compiler/scala/tools/nsc/doc/SourcelessComments.scala
@@ -210,39 +210,6 @@ abstract class SourcelessComments {
 
     /*******************************************************************/
 
-    comment(AnyValClass) = new DocComment("""
-      /** Class `AnyVal` is the root class of all ''value types''.
-        *
-        * `AnyVal` has a fixed number of subclasses, which describe values which are not implemented as objects in the
-        * underlying host system.
-        *
-        * Classes [[scala.Double]], [[scala.Float]], [[scala.Long]], [[scala.Int]], [[scala.Char]], [[scala.Short]],
-        * and [[scala.Byte]] are together called ''numeric value types''. Classes [[scala.Byte]], [[scala.Short]], and
-        * [[scala.Char]] are called ''subrange types''. Subrange types, as well as [[scala.Int]] and [[scala.Long]] are
-        * called ''integer types'', whereas [[scala.Float]] and [[scala.Double]] are called ''floating point types''. */
-      """)
-
-    comment(BooleanClass) = new DocComment("""
-      /** Class `Boolean` has only two values: `true` and `false`. */
-      """)
-
-    comment(UnitClass) = new DocComment("""
-      /** Class `Unit` has only one value: `()`. */
-      """)
-
-    List(ByteClass, CharClass, DoubleClass, LongClass, FloatClass, IntClass, ShortClass) foreach { sym =>
-      val maxValue = "MAX_" + sym.name.toString().toUpperCase()
-      val minValue = "MIN_" + sym.name.toString().toUpperCase()
-      comment(sym) = new DocComment("""
-        /** Class `""" + sym.name + """` belongs to the value classes whose instances are not represented as objects by
-          * the underlying host system.  There is an implicit conversion from instances of `""" + sym.name + """` to
-          * instances of [[scala.runtime.Rich""" + sym.name + """]] which provides useful non-primitive operations.
-          * All value classes inherit from class [[scala.AnyVal]].
-          *
-          * Values `""" + maxValue + """` and `""" + minValue + """` are defined in object [[scala.Math]]. */
-        """)
-    }
-
     comment
   }