Added some documentation to the methods in Pred...

Added some documentation to the methods in Predef which utilize
@elidable. No review.

1 files changed, 49 insertions, 3 deletions

diff --git a/src/library/scala/Predef.scala b/src/library/scala/Predef.scala
index d022b3e4a5..20d70edadf 100644
--- a/src/library/scala/Predef.scala
+++ b/src/library/scala/Predef.scala
@@ -14,6 +14,8 @@ package scala
 import collection.immutable.StringOps
 import collection.mutable.ArrayOps
 import collection.generic.CanBuildFrom
+import annotation.elidable
+import annotation.elidable.ASSERTION
 
 /** The <code>Predef</code> object provides definitions that are
  *  accessible in all Scala compilation units without explicit
@@ -64,38 +66,82 @@ object Predef extends LowPriorityImplicits {
     throw new Throwable()
   }
 
-  import annotation.elidable
-  import annotation.elidable.ASSERTION
-
+  /** Tests an expression, throwing an AssertionError if false.
+   *  Calls to this method will not be generated if -Xelide-below
+   *  is at least ASSERTION.
+   *
+   *  @see elidable
+   *  @param p   the expression to test
+   */
   @elidable(ASSERTION)
   def assert(assertion: Boolean) {
     if (!assertion)
       throw new java.lang.AssertionError("assertion failed")
   }
 
+  /** Tests an expression, throwing an AssertionError if false.
+   *  Calls to this method will not be generated if -Xelide-below
+   *  is at least ASSERTION.
+   *
+   *  @see elidable
+   *  @param p   the expression to test
+   *  @param msg a String to include in the failure message
+   */
   @elidable(ASSERTION)
   def assert(assertion: Boolean, message: => Any) {
     if (!assertion)
       throw new java.lang.AssertionError("assertion failed: "+ message)
   }
 
+  /** Tests an expression, throwing an AssertionError if false.
+   *  This method differs from assert only in the intent expressed:
+   *  assert contains a predicate which needs to be proven, while
+   *  assume contains an axiom for a static checker.  Calls to this method
+   *  will not be generated if -Xelide-below is at least ASSERTION.
+   *
+   *  @see elidable
+   *  @param p   the expression to test
+   */
   @elidable(ASSERTION)
   def assume(assumption: Boolean) {
     if (!assumption)
       throw new java.lang.AssertionError("assumption failed")
   }
 
+  /** Tests an expression, throwing an AssertionError if false.
+   *  This method differs from assert only in the intent expressed:
+   *  assert contains a predicate which needs to be proven, while
+   *  assume contains an axiom for a static checker.  Calls to this method
+   *  will not be generated if -Xelide-below is at least ASSERTION.
+   *
+   *  @see elidable
+   *  @param p   the expression to test
+   *  @param msg a String to include in the failure message
+   */
   @elidable(ASSERTION)
   def assume(assumption: Boolean, message: => Any) {
     if (!assumption)
       throw new java.lang.AssertionError("assumption failed: "+ message)
   }
 
+  /** Tests an expression, throwing an IllegalArgumentException if false.
+   *  This method is similar to assert, but blames the caller of the method
+   *  for violating the condition.
+   *
+   *  @param p   the expression to test
+   */
   def require(requirement: Boolean) {
     if (!requirement)
       throw new IllegalArgumentException("requirement failed")
   }
 
+  /** Tests an expression, throwing an IllegalArgumentException if false.
+   *  This method is similar to assert, but blames the caller of the method
+   *  for violating the condition.
+   *
+   *  @param p   the expression to test
+   *  @param msg a String to include in the failure message
+   */
   def require(requirement: Boolean, message: => Any) {
     if (!requirement)
       throw new IllegalArgumentException("requirement failed: "+ message)