Improved the documentation for Application to b...

Improved the documentation for Application to be clearer about its
caveats.

1 files changed, 22 insertions, 2 deletions

diff --git a/src/library/scala/Application.scala b/src/library/scala/Application.scala
index da34a4d224..cd5e47fdf4 100644
--- a/src/library/scala/Application.scala
+++ b/src/library/scala/Application.scala
@@ -15,8 +15,8 @@ import java.lang.System.getProperty
 import scala.compat.Platform.currentTime
 
 /** <p>
- *    The <code>Application</code> class can be used to quickly turn objects
- *    into executable programs. Here is an example:
+ *    The <code>Application</code> trait can be used to quickly turn objects
+ *    into executable programs, but is <em>not recommended</em>.  Here is an example:
  *  </p><pre>
  *  <b>object</b> Main <b>extends</b> Application {
  *    Console.println("Hello World!")
@@ -36,6 +36,26 @@ import scala.compat.Platform.currentTime
  *  </p><pre>
  *  java -Dscala.time Main
  *  </pre>
+ *  <p>In practice the <code>Application</code> trait has a number of serious
+ *  pitfalls:
+ *  <ul>
+ *    <li>As described above, there is no way to obtain the
+ *    command-line arguments because all code in body of an <code>object</code>
+ *    extending <code>Application</code> is run as part of the static initialization
+ *    which occurs before <code>Application</code>'s <code>main</code> method
+ *    even begins execution.</li>
+ *    <li> Threaded code that references the object will block until static
+ *    initialization is complete.  However, because the entire execution of an
+ *    <code>object</code> extending <code>Application</code> takes place during
+ *    static initialization, concurrent code will <em>always</em> deadlock if
+ *    it must synchronize with the enclosing object.</li>
+ *    <li>Static initializers are run only once during program execution, and
+ *    JVM authors usually assume their execution to be relatively short.
+ *    Therefore, certain JVM configurations may become confused, or simply fail to
+ *    optimize or JIT the code in the body of an <code>object</code> extending
+ *    <code>Application</code>.  This can lead to a significant
+ *    performance degradation.</li>
+ *  </p>
  *
  *  @author  Matthias Zenger
  *  @version 1.0, 10/09/2003