[#700] Change default exit codes to 1 for Exceptions, 2 for invalid usage. Add links to ExitCode javadoc.

Closes #700

RELEASE-NOTES.md

@@ -32,6 +32,7 @@ Picocli follows [semantic versioning](http://semver.org/).
 - [#698] Reduce `reflect-config.json` used by GraalVM native-image generation
 - [#500] Add a generic and extensible picocli annotation processor
 - [#699] Add annotation processor that generates `reflect-config.json` during build
+- [#700] Change default exit codes to `1` for Exceptions, `2` for invalid usage. Add links to `ExitCode` javadoc.
 
 ## <a name="4.0.0-beta-1-deprecated"></a> Deprecations
 

docs/index.adoc

@@ -1307,7 +1307,7 @@ assert 3 == new CommandLine(new Gesture()).execute();
 
 === Exception Exit Codes
 
-By default, the `execute` method returns `CommandLine.ExitCode.USAGE` (`64`) for invalid input, and `CommandLine.ExitCode.SOFTWARE` (`70`) when an exception occurred in the Runnable, Callable or command method. (For reference, these values are `EX_USAGE` and `EX_SOFTWARE`, respectively, from Unix and Linux https://www.freebsd.org/cgi/man.cgi?query=sysexits&sektion=3[sysexits.h]). This can be customized with the `@Command` annotation. For example:
+By default, the `execute` method returns `CommandLine.ExitCode.OK` (`0`) on success, `CommandLine.ExitCode.SOFTWARE` (`1`) when an exception occurred in the Runnable, Callable or command method, and `CommandLine.ExitCode.USAGE` (`2`) for invalid input. (These are common values according to https://stackoverflow.com/questions/1101957/are-there-any-standard-exit-status-codes-in-linux/40484670#40484670[this StackOverflow answer]). This can be customized with the `@Command` annotation. For example:
 
 ```java 
 @Command(exitCodeOnInvalidInput = 123,

src/main/java/picocli/CommandLine.java

@@ -853,20 +853,33 @@ public class CommandLine {
     /**
      * Defines some exit codes used by picocli as default return values from the {@link #execute(String...) execute}
      * and {@link #executeHelpRequest(ParseResult) executeHelpRequest} methods.
-     * <p>Commands can override these defaults with annotations (e.g. {@code @Command(exitCodeOnInvalidInput = 12345)}
+     * <p>Commands can override these defaults with annotations (e.g. {@code @Command(exitCodeOnInvalidInput = 64, exitCodeOnExecutionException = 70)}
      * or programmatically (e.g. {@link CommandSpec#exitCodeOnInvalidInput(int)}).</p>
      * <p>Additionally, there are several mechanisms for commands to return custom exit codes.
      * See the javadoc of the {@link #execute(String...) execute} method for details.</p>
+     * <h3>Standard Exit Codes</h3>
+     * <p>There are a few conventions, but there is <a href="https://stackoverflow.com/questions/1101957/are-there-any-standard-exit-status-codes-in-linux/40484670#40484670">no
+     * standard</a>. The specific set of codes returned is unique to the program that sets it.
+     * Typically an exit code of zero indicates success, any non-zero exit code indicates failure. For reference, here are a few conventions:</p>
+     * <ul>
+     *   <li><a href="https://en.wikipedia.org/wiki/Exit_status">Wikipedia page on Exit Status</a></li>
+     *   <li><a href="http://www.faqs.org/docs/abs/HTML/exitcodes.html#EXITCODESREF">Bash exit codes</a></li>
+     *   <li><a href="https://www.freebsd.org/cgi/man.cgi?query=sysexits&amp;sektion=3">FreeBSD exit codes</a></li>
+     *   <li><a href="http://www.hiteksoftware.com/knowledge/articles/049.htm">Windows exit codes</a></li>
+     * </ul>
+     * <h3>Valid Ranges</h3>
+     * <p>Note that *nix shells may restrict exit codes to the 0-255 range, DOS seems to allow larger numbers.
+     * See this <a href="https://stackoverflow.com/questions/179565/exitcodes-bigger-than-255-possible">StackOverflow question</a>.</p>
      * @since 4.0 */
     public static final class ExitCode {
         /** Return value from the {@link #execute(String...) execute} and
          * {@link #executeHelpRequest(ParseResult) executeHelpRequest} methods signifying successful termination.
-         * <p>The value of this constant is {@value}, following unix C/C++ system programming <a href="https://www.freebsd.org/cgi/man.cgi?query=sysexits&amp;sektion=3">conventions</a>.</p> */
+         * <p>The value of this constant is {@value}, following unix C/C++ system programming <a href="">conventions</a>.</p> */
         public static final int OK = 0;
-        /** Return value from the {@link #execute(String...) execute} method signifying command line usage error: user input for the command was incorrect, e.g., the wrong number of arguments, a bad flag, a bad syntax in a parameter, or whatever. <p>The value of this constant is {@value}, following unix C/C++ system programming <a href="https://www.freebsd.org/cgi/man.cgi?query=sysexits&amp;sektion=3">conventions</a>.</p>*/
-        public static final int USAGE = 64;
-        /** Return value from the {@link #execute(String...) execute} method signifying internal software error: an exception occurred when invoking the Runnable, Callable or Method user object of a command. <p>The value of this constant is {@value}, following unix C/C++ system programming <a href="https://www.freebsd.org/cgi/man.cgi?query=sysexits&amp;sektion=3">conventions</a>.</p> */
-        public static final int SOFTWARE = 70;
+        /** Return value from the {@link #execute(String...) execute} method signifying internal software error: an exception occurred when invoking the Runnable, Callable or Method user object of a command. <p>The value of this constant is {@value}.</p> */
+        public static final int SOFTWARE = 1;
+        /** Return value from the {@link #execute(String...) execute} method signifying command line usage error: user input for the command was incorrect, e.g., the wrong number of arguments, a bad flag, a bad syntax in a parameter, or whatever. <p>The value of this constant is {@value}.</p>*/
+        public static final int USAGE = 2;
         private ExitCode() {} // don't instantiate
     }