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