Fixes SI-5199 through improved API docs

1 files changed, 29 insertions, 3 deletions

diff --git a/src/library/scala/DelayedInit.scala b/src/library/scala/DelayedInit.scala
index e898bca720..52a38ca6f7 100644
--- a/src/library/scala/DelayedInit.scala
+++ b/src/library/scala/DelayedInit.scala
@@ -8,15 +8,41 @@
 
 package scala
 
-/** Classes and traits inheriting the `DelayedInit` marker trait
- *  will have their initialization code rewritten as follows:
+/** Classes and objects (but note, not traits) inheriting the `DelayedInit` 
+ *  marker trait will have their initialization code rewritten as follows:
  *  `code` becomes `delayedInit(code)`.
  *
  *  Initialization code comprises all statements and all value definitions
  *  that are executed during initialization.
  *
+ *  Example:
+ *  {{{
+ *    trait Helper extends DelayedInit {
+ *      def delayedInit(body: => Unit) = {
+ *        println("dummy text, printed before initialization of C")
+ *        body // evaluates the initialization code of C
+ *      }
+ *    }
+ *
+ *    class C extends Helper {
+ *      println("this is the initialization code of C")
+ *    }
+ *
+ *    object Test extends App {
+ *      val c = new C
+ *    }
+ *  }}}
+ *  
+ *  Should result in the following being printed:
+ *  {{{
+ *    dummy text, printed before initialization of C
+ *    this is the initialization code of C
+ *  }}}
+ *
+ *  @see "Delayed Initialization" subsection of the Scala Language Specification (section 5.1)
+ *
  *  @author  Martin Odersky
  */
 trait DelayedInit {
   def delayedInit(x: => Unit): Unit
-}
+}
\ No newline at end of file