[#350] Enhancement: Improve error message for usageHelp and `versio…

…nHelp` validation.

Closes #350

RELEASE-NOTES.md

@@ -1,5 +1,45 @@
 # picocli Release Notes
 
+# <a name="3.0.0-alpha-6"></a> Picocli 3.0.0-alpha-6 (UNRELEASED)
+The picocli community is pleased to announce picocli 3.0.0-alpha-6.
+
+This release contains enhancements and bug fixes.
+
+This is the twenty-sixth public release.
+Picocli follows [semantic versioning](http://semver.org/).
+
+## <a name="3.0.0-alpha-6-toc"></a> Table of Contents
+* [New and noteworthy](#3.0.0-alpha-6-new)
+* [Promoted features](#3.0.0-alpha-6-promoted)
+* [Fixed issues](#3.0.0-alpha-6-fixes)
+* [Deprecations](#3.0.0-alpha-6-deprecated)
+* [Potential breaking changes](#3.0.0-alpha-6-breaking-changes)
+
+## <a name="3.0.0-alpha-5-new"></a> New and Noteworthy
+
+
+## <a name="3.0.0-alpha-6-promoted"></a> Promoted Features
+Promoted features are features that were incubating in previous versions of picocli but are now supported and subject to backwards compatibility. 
+
+No features have been promoted in this picocli release.
+
+## <a name="3.0.0-alpha-6-fixes"></a> Fixed issues
+- [#350] Enhancement: Improve error message for `usageHelp` and `versionHelp` validation.
+
+## <a name="3.0.0-alpha-6-deprecated"></a> Deprecations
+See [3.0.0-alpha-1](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-1#3.0.0-alpha-1-deprecated)
+
+## <a name="3.0.0-alpha-6-breaking-changes"></a> Potential breaking changes
+See also breaking changes for 
+[3.0.0-alpha-5](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-5#3.0.0-alpha-5-breaking-changes),
+[3.0.0-alpha-4](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-4#3.0.0-alpha-4-breaking-changes),
+[3.0.0-alpha-3](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-3#3.0.0-alpha-3-breaking-changes),
+[3.0.0-alpha-2](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-2#3.0.0-alpha-2-breaking-changes),
+and [3.0.0-alpha-1](https://github.com/remkop/picocli/releases/tag/v3.0.0-alpha-1#3.0.0-alpha-1-breaking-changes).
+
+
+
+
 # <a name="3.0.0-alpha-5"></a> Picocli 3.0.0-alpha-5
 The picocli community is pleased to announce picocli 3.0.0-alpha-5.
 

src/main/java/picocli/CommandLine.java

@@ -2753,19 +2753,30 @@ public static class CommandSpec {
             void validate() {
                 Collections.sort(positionalParameters, new PositionalParametersSorter());
                 validatePositionalParameters(positionalParameters);
-                int usageHelpCount = 0, versionHelpCount = 0;
+                List<String> wrongUsageHelpAttr = new ArrayList<String>();
+                List<String> wrongVersionHelpAttr = new ArrayList<String>();
+                List<String> usageHelpAttr = new ArrayList<String>();
+                List<String> versionHelpAttr = new ArrayList<String>();
                 for (OptionSpec option : options()) {
                     if (option.usageHelp()) {
-                        usageHelpCount++;
-                        if (!isBoolean(option.type())) { throw new InitializationException("Non-boolean options (like " + option.names()[0] + ") should not be marked as 'usageHelp=true'."); }
+                        usageHelpAttr.add(option.names()[0]);
+                        if (!isBoolean(option.type())) { wrongUsageHelpAttr.add(option.names()[0]); }
                     }
                     if (option.versionHelp()) {
-                        versionHelpCount++;
-                        if (!isBoolean(option.type())) { throw new InitializationException("Non-boolean options (like " + option.names()[0] + ") should not be marked as 'versionHelp=true'."); }
+                        versionHelpAttr.add(option.names()[0]);
+                        if (!isBoolean(option.type())) { wrongVersionHelpAttr.add(option.names()[0]); }
                     }
                 }
-                if (usageHelpCount > 1)   { commandLine.tracer.warn("Multiple options are marked as 'usageHelp=true'. Usually there is only one --help option that displays usage help."); }
-                if (versionHelpCount > 1) { commandLine.tracer.warn("Multiple options are marked as 'versionHelp=true'. Usually there is only one --version option that displays version information."); }
+                String wrongType = "Non-boolean options like %s should not be marked as '%s=true'. Usually a command has one %s boolean flag that triggers display of the %s. Alternatively, consider using @Command(mixinStandardHelpOptions = true) on your command instead.";
+                String multiple = "Multiple options %s are marked as '%s=true'. Usually a command has only one %s option that triggers display of the %s. Alternatively, consider using @Command(mixinStandardHelpOptions = true) on your command instead.%n";
+                if (!wrongUsageHelpAttr.isEmpty()) {
+                    throw new InitializationException(String.format(wrongType, wrongUsageHelpAttr, "usageHelp", "--help", "usage help message"));
+                }
+                if (!wrongVersionHelpAttr.isEmpty()) {
+                    throw new InitializationException(String.format(wrongType, wrongVersionHelpAttr, "versionHelp", "--version", "version information"));
+                }
+                if (usageHelpAttr.size() > 1)   { new Tracer().warn(multiple, usageHelpAttr, "usageHelp", "--help", "usage help message"); }
+                if (versionHelpAttr.size() > 1) { new Tracer().warn(multiple, versionHelpAttr, "versionHelp", "--version", "version information"); }
             }
 
             /** Returns the user object associated with this command.

src/test/java/picocli/CommandLineModelTest.java

@@ -1176,7 +1176,7 @@ public void testMultipleUsageHelpOptions() {
         systemErrRule.clearLog();
         new CommandLine(cmd);
         assertEquals("", systemOutRule.getLog());
-        assertEquals("[picocli WARN] Multiple options are marked as 'usageHelp=true'. Usually there is only one --help option that displays usage help.", systemErrRule.getLog());
+        assertEquals(String.format("[picocli WARN] Multiple options [-x, -h] are marked as 'usageHelp=true'. Usually a command has only one --help option that triggers display of the usage help message. Alternatively, consider using @Command(mixinStandardHelpOptions = true) on your command instead.%n"), systemErrRule.getLog());
     }
 
     @Test
@@ -1190,7 +1190,7 @@ public void testMultipleVersionHelpOptions() {
         systemErrRule.clearLog();
         new CommandLine(cmd);
         assertEquals("", systemOutRule.getLog());
-        assertEquals("[picocli WARN] Multiple options are marked as 'versionHelp=true'. Usually there is only one --version option that displays version information.", systemErrRule.getLog());
+        assertEquals(String.format("[picocli WARN] Multiple options [-x, -V] are marked as 'versionHelp=true'. Usually a command has only one --version option that triggers display of the version information. Alternatively, consider using @Command(mixinStandardHelpOptions = true) on your command instead.%n"), systemErrRule.getLog());
     }
 
     @Test
@@ -1199,7 +1199,7 @@ public void testNonBooleanUsageHelpOptions() {
         try {
             new CommandLine(cmd);
         } catch (InitializationException ex) {
-            assertEquals("Non-boolean options (like -z) should not be marked as 'usageHelp=true'.", ex.getMessage());
+            assertEquals("Non-boolean options like [-z] should not be marked as 'usageHelp=true'. Usually a command has one --help boolean flag that triggers display of the usage help message. Alternatively, consider using @Command(mixinStandardHelpOptions = true) on your command instead.", ex.getMessage());
         }
     }
 
@@ -1209,7 +1209,7 @@ public void testNonBooleanVersionHelpOptions() {
         try {
             new CommandLine(cmd);
         } catch (InitializationException ex) {
-            assertEquals("Non-boolean options (like -x) should not be marked as 'versionHelp=true'.", ex.getMessage());
+            assertEquals("Non-boolean options like [-x] should not be marked as 'versionHelp=true'. Usually a command has one --version boolean flag that triggers display of the version information. Alternatively, consider using @Command(mixinStandardHelpOptions = true) on your command instead.", ex.getMessage());
         }
     }