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.

1 files changed, 26 insertions, 4 deletions

diff --git a/src/library/scala/Boolean.scala b/src/library/scala/Boolean.scala
index dc2076cb1d..220fc752c3 100755
--- a/src/library/scala/Boolean.scala
+++ b/src/library/scala/Boolean.scala
@@ -10,8 +10,12 @@
 
 package scala
 
-import java.{ lang => jl }
-
+/** `Boolean` 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.Boolean]] => [[scala.runtime.RichBoolean]]
+ *  which provides useful non-primitive operations.
+ */
 final class Boolean extends AnyVal {
   def unary_! : Boolean = sys.error("stub")
 
@@ -28,7 +32,25 @@ final class Boolean extends AnyVal {
 }
 
 object Boolean extends AnyValCompanion {
+  /** Transform a value type into a boxed reference type.
+   *
+   *  @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)
+
+  /** 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 java.lang.Boolean.
+   *
+   *  @param  x   the Boolean to be unboxed.
+   *  @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()
+
+  /** The String representation of the scala.Boolean companion object.
+   */
   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()
+
 }
\ No newline at end of file