clarifications for how sketch args work

core/src/processing/core/PApplet.java

@@ -189,8 +189,8 @@ public class PApplet implements PConstants {
 
   /**
    * Command line options passed in from main().
-   * <p>
    * This does not include the arguments passed in to PApplet itself.
+   * @see PApplet#main
    */
   public String[] args;
 
@@ -9261,16 +9261,23 @@ public class PApplet implements PConstants {
   /**
    * main() method for running this class from the command line.
    * <p>
-   * <B>The options shown here are not yet finalized and will be
-   * changing over the next several releases.</B>
+   * Usage: PApplet [options] &lt;class name&gt; [sketch args]
+   * <ul>
+   * <li>The [options] are one or several of the parameters seen below.
+   * <li>The class name is required. If you're running outside the PDE and
+   * your class is in a package, this should include the full name. That means
+   * that if the class is called Sketchy and the package is com.sketchycompany
+   * then com.sketchycompany.Sketchy should be used as the class name.
+   * <li>The [sketch args] are any command line parameters you want to send to
+   * the sketch itself. These will be passed into the args[] array in PApplet.
    * <p>
-   * The simplest way to turn and applet into an application is to
+   * The simplest way to turn and sketch into an application is to
    * add the following code to your program:
    * <PRE>static public void main(String args[]) {
-   *   PApplet.main("YourSketchName", args);
+   *   PApplet.main("YourSketchName");
    * }</PRE>
-   * This will properly launch your applet from a double-clickable
-   * .jar or from the command line.
+   * That will properly launch your code from a double-clickable .jar
+   * or from the command line.
    * <PRE>
    * Parameters useful for launching or also used by the PDE:
    *
@@ -9306,6 +9313,11 @@ public class PApplet implements PConstants {
    *
    * --editor-location=x,y position of the upper-lefthand corner of the
    *                       editor window, for placement of applet window
+   *
+   * All parameters *after* the sketch class name are passed to the sketch
+   * itself and available from its 'args' array while the sketch is running.
+   *
+   * @see PApplet#args
    * </PRE>
    */
   static public void main(final String[] args) {
@@ -9315,7 +9327,7 @@ public class PApplet implements PConstants {
 
   /**
    * Convenience method so that PApplet.main("YourSketch") launches a sketch,
-   * rather than having to wrap it into a String array.
+   * rather than having to wrap it into a single element String array.
    * @param mainClass name of the class to load (with package if any)
    */
   static public void main(final String mainClass) {
@@ -9328,18 +9340,33 @@ public class PApplet implements PConstants {
    * sketch, rather than having to wrap it into a String array, and appending
    * the 'args' array when not null.
    * @param mainClass name of the class to load (with package if any)
-   * @param args command line arguments to pass to the sketch
+   * @param args command line arguments to pass to the sketch's 'args' array.
+   *             Note that this is *not* the same as the args passed to PApplet
+   *             such as --display and others.
    */
-  static public void main(final String mainClass, final String[] passedArgs) {
+  static public void main(final String mainClass, final String[] sketchArgs) {
     String[] args = new String[] { mainClass };
-    if (passedArgs != null) {
-      args = concat(args, passedArgs);
+    if (sketchArgs != null) {
+      args = concat(args, sketchArgs);
     }
     runSketch(args, null);
   }
 
 
-  static public void runSketch(final String[] args, final PApplet constructedApplet) {
+  /*
+  static public void runSketch(final String[] args,
+                               final PApplet constructedApplet) {
+    EventQueue.invokeLater(new Runnable() {
+      public void run() {
+        runSketchEDT(args, constructedApplet);
+      }
+    });
+  }
+  */
+
+
+  static public void runSketch(final String[] args,
+                               final PApplet constructedApplet) {
     // Supposed to help with flicker, but no effect on OS X.
     // TODO IIRC this helped on Windows, but need to double check.
     System.setProperty("sun.awt.noerasebackground", "true");
@@ -9347,8 +9374,8 @@ public class PApplet implements PConstants {
     Toolkit.getDefaultToolkit().setDynamicLayout(true);
 
     if (args.length < 1) {
-      System.err.println("Usage: PApplet <appletname>");
-      System.err.println("For additional options, see the Javadoc for PApplet");
+      System.err.println("Usage: PApplet [options] <class name> [sketch args]");
+      System.err.println("See the Javadoc for PApplet for an explanation.");
       System.exit(1);
     }
 
@@ -9599,9 +9626,8 @@ public class PApplet implements PConstants {
 
 
   /**
-   * These methods provide a means for running an already-constructed
-   * sketch. In particular, it makes it easy to launch a sketch in
-   * Jython:
+   * Convenience method for Python Mode to run an already-constructed sketch.
+   * This makes it makes it easy to launch a sketch in Jython:
    *
    * <pre>class MySketch(PApplet):
    *     pass
@@ -9619,6 +9645,7 @@ public class PApplet implements PConstants {
   }
 
 
+  /** Convenience method for Python Mode */
   protected void runSketch() {
     runSketch(new String[0]);
   }