[#1191] improve javadoc

picocli-groovy/src/main/java/picocli/groovy/PicocliBaseScript2.java

@@ -21,8 +21,9 @@ import java.util.concurrent.Callable;
  * Scripts may install this base script via the {@link PicocliScript2} annotation or via the standard Groovy
  * {@code @groovy.transform.BaseScript(picocli.groovy.PicocliBaseScript2)} annotation, but
  * the {@code @PicocliScript2} annotation is preferred since it enables scripts to use the
- * {@code @Command} annotation. Example usage:
+ * {@code @Command} annotation.
  * </p>
+ * <h1>Example usage</h1>
  * <pre>
  * &#64;Command(name = "myCommand", description = "does something special")
  * &#64;PicocliScript2
@@ -38,7 +39,9 @@ import java.util.concurrent.Callable;
  * </p><p>
  * See the {@link #run()} method for a detailed break-down of the steps the base class takes
  * before the statements in the script body are executed.
- * </p><p>
+ * </p>
+ * <h1>PicocliBaseScript2 vs PicocliBaseScript</h1>
+ * <p>
  * This class has the following improvements over {@link PicocliBaseScript}:
  * </p>
  * <ul>
@@ -89,7 +92,7 @@ public abstract class PicocliBaseScript2 extends Script implements Callable<Obje
      *   <li>The {@link CommandLine#execute(String...)} method is called with the script arguments.
      *     This initialises all {@code @Field} variables annotated with {@link CommandLine.Option} or
      *     {@link CommandLine.Parameters}, unless the user input was invalid.</li>
-     *   <li>If the user input was invalid, the command line arguments are printed to standard err, followed by,
+     *   <li>If the user input was invalid, the command line arguments are printed to standard err, followed by
      *     an error message and the usage message.
      *     Then, the script exits.
      *     This may be customized by overriding {@link #customize(CommandLine)} and setting a custom
@@ -104,8 +107,10 @@ public abstract class PicocliBaseScript2 extends Script implements Callable<Obje
      *   <li>If an exception occurs during execution, this exception is rethrown.</li>
      * </ol>
      * <h1>Exit Code</h1>
+     * <p>After execution, the {@code PicocliBaseScript2} class sets the exit code in the {@code exitCode} property of the script.</p>
      * <p>
-     *     Scripts that want to control the exit code need to override the {@link #run()} method and call {@code System.exit}.
+     *     Scripts that want to control the exit code of the process executing the script
+     *     need to override the {@link #run()} method and call {@code System.exit}.
      *     For example:
      * </p><pre>{@code
      * @Override

picocli-groovy/src/main/java/picocli/groovy/PicocliScript2.java

@@ -34,9 +34,8 @@ import java.lang.annotation.Target;
  * Also, any {@link picocli.CommandLine.Command} annotation on the same variable or import statement will be added to
  * the script class. With the {@code @Command} annotation scripts can customize elements shown in the usage message
  * like command name, description, headers, footers etc.
- * </p><p>
- * Example usage:
  * </p>
+ * <h1>Example usage</h1>
  * <pre>
  * &#64;Command(name = "myCommand", description = "does something special")
  * &#64;PicocliScript2
@@ -62,8 +61,10 @@ import java.lang.annotation.Target;
  * Otherwise, this annotation works similar to the Groovy built-in {@link groovy.transform.BaseScript}.
  * Using this annotation will override the base script set by Groovy compiler or
  * {@link org.codehaus.groovy.control.CompilerConfiguration} of {@link groovy.lang.GroovyShell}.
- * </p><p>
- * To customize further, a base script class extending {@link PicocliBaseScript2}
+ * </p>
+ * <h1>Customizing</h1>
+ * <p>
+ * To customize, a base script class extending {@link PicocliBaseScript2}
  * may be specified as the value of this annotation, for example:
  * </p><pre>
  * &#64;PicocliScript2(com.mycompany.MyScriptBaseClass)
@@ -78,6 +79,7 @@ import java.lang.annotation.Target;
  * import com.mycompany.MyScriptBaseClass
  * &#64;PicocliScript2 MyScriptBaseClass theScript;
  * </pre>
+ * <h1>PicocliBaseScript2 vs PicocliBaseScript</h1>
  * <p>
  * This class has the following improvements over {@link PicocliScript}:
  * </p>