Fleshed out the @elidable documentation.

1 files changed, 43 insertions, 15 deletions

diff --git a/src/library/scala/annotation/elidable.scala b/src/library/scala/annotation/elidable.scala
index 145c404a28..053cdba220 100644
--- a/src/library/scala/annotation/elidable.scala
+++ b/src/library/scala/annotation/elidable.scala
@@ -10,25 +10,53 @@ package scala.annotation
 
 import java.util.logging.Level
 
-/** An annotation for methods whose body might be removed in the generated
- *  code.
+/** An annotation for methods whose bodies may be excluded
+ *  from compiler-generated bytecode.
  *
  *  Behavior is influenced by passing `-Xelide-below <arg>` to `scalac`.
- *  The body of methods marked elidable will be omitted from generated code
- *  if the priority given the annotation is lower than to the command line
- *  argument. If the method has a result type other than Unit, its return
- *  value will be the zero value of the type (0 for numeric types, false for
- *  boolean and null for reference types).
- *  Examples:
- *  {{{
- *  import annotation.elidable._
+ *  Calls to methods marked elidable (as well as the method body) will
+ *  be omitted from generated code if the priority given the annotation
+ *  is lower than that given on the command line.
  *
- *    @elidable(WARNING) def foo = log("foo")
- *    @elidable(FINE) def bar = log("bar")
+ *     @elidable(123)           // annotation priority
+ *     scalac -Xelide-below 456 // command line priority
  *
- *  scalac -Xelide-below=1000
- *  }}}
- *  @since 2.8
+ *  The method call will be replaced with an expression which depends on
+ *  the type of the elided expression.  In decreasing order of precedence:
+ *
+ *    Unit            ()
+ *    Boolean         false
+ *    T <: AnyVal     0
+ *    T >: Null       null
+ *    T >: Nothing    Predef.???
+ *
+ *  Complete example:
+ {{{
+   import annotation._, elidable._
+   object Test extends App {
+     def expensiveComputation(): Int = { Thread.sleep(1000) ; 172 }
+
+     @elidable(WARNING) def warning(msg: String) = println(msg)
+     @elidable(FINE) def debug(msg: String)      = println(msg)
+     @elidable(FINE) def computedValue           = expensiveComputation()
+
+     warning("Warning! Danger! Warning!")
+     debug("Debug! Danger! Debug!")
+     println("I computed a value: " + computedValue)
+   }
+   % scalac example.scala && scala Test
+   Warning! Danger! Warning!
+   Debug! Danger! Debug!
+   I computed a value: 172
+
+   // INFO lies between WARNING and FINE
+   % scalac -Xelide-below INFO example.scala && scala Test
+   Warning! Danger! Warning!
+   I computed a value: 0   
+ }}} 
+ *
+ *  @author   Paul Phillips
+ *  @since    2.8
  */
 final class elidable(final val level: Int) extends annotation.StaticAnnotation {}