Small overhaul to the command-line parameter documentation (#2383)

Improving several things here:
- Consistent labeling of parameter type
- Adding units (seconds, milliseconds, etc) to all options where necessary
- Listing default values
- Improving clarity of messages with consistency of terms, etc and various word usements

Fixing indentation in one place

java/server/src/org/openqa/grid/internal/utils/configuration/GridConfiguration.java

@@ -28,32 +28,32 @@ public class GridConfiguration extends StandaloneConfiguration {
 
   @Parameter(
     names = "-cleanUpCycle",
-    description = "<Integer> in ms. How often a proxy on the hub will check for timed out thread. Must have timeout option specified also"
+    description = "<Integer> in ms : specifies how often the hub will poll running proxies for timed-out (i.e. hung) threads. Must also specify \"timeout\" option"
   )
   public Integer cleanUpCycle;
 
   @Parameter(
     names = "-custom",
-    description = "comma separated parameters for custom grid extensions. example: -custom myParamA=Value1,myParamB=Value2",
+    description = "<String> : NOT RECOMMENDED--may be deprecated to encourage proper servlet customization. Comma separated key=value pairs for custom grid extensions. example: -custom myParamA=Value1,myParamB=Value2",
     converter = CustomConverter.class
   )
   public Map<String, String> custom = new HashMap<>();
 
   @Parameter(
     names = "-host",
-    description =  "<IP | hostname> : usually not needed and determined automatically. For exotic network configuration, network with VPN, specifying the host might be necessary."
+    description =  "<String> IP or hostname : usually determined automatically. Most commonly useful in exotic network configurations (e.g. network with VPN)"
   )
   public String host;
 
   @Parameter(
     names = "-maxSession",
-    description = "<Integer> max number of tests that can run at the same time on the node, independently of the browser used."
+    description = "<Integer> max number of tests that can run at the same time on the node, irrespective of the browser used"
   )
   public Integer maxSession = 1;
 
   @Parameter(
     names = {"-servlet", "-servlets"},
-    description = "list of extra servlets this hub will display. Allows to present custom view of the hub for monitoring and management purpose. Specify multiple on the command line: -servlet tld.company.ServletA -servlet tld.company.ServletB. The servlet will accessible under the path  /grid/admin/ServletA /grid/admin/ServletB"
+    description = "<String> : list of extra servlets this hub will display. Allows to present custom view of the hub for monitoring and management purposes. Specify multiple on the command line: -servlet tld.company.ServletA -servlet tld.company.ServletB. The servlet must exist in the path: /grid/admin/ServletA /grid/admin/ServletB"
   )
   public List<String> servlets;
 

java/server/src/org/openqa/grid/internal/utils/configuration/GridHubConfiguration.java

@@ -38,39 +38,39 @@ public class GridHubConfiguration extends GridConfiguration {
 
   @Parameter(
     names = "-hubConfig",
-    description =  "a JSON file following grid2 format that defines the hub properties."
+    description =  "<String> filename: a JSON file (following grid2 format), which defines the hub properties"
   )
   public String hubConfig;
 
   @Parameter(
     names = "-jettyMaxThreads",
-    description = "max number of thread for Jetty. Default is normally 255."
+    description = "<Integer> : max number of thread for Jetty. Default is 255"
   )
   public Integer jettyMaxThreads;
 
   @Parameter(
     names = {"-matcher", "-capabilityMatcher"},
-    description = "a class implementing the CapabilityMatcher interface. Defaults to org.openqa.grid.internal.utils.DefaultCapabilityMatcher. Specify the logic the hub will follow to define if a request can be assigned to a node.Change this class if you want to have the matching process use regular expression instead of exact match for the version of the browser for instance. All the nodes of a grid instance will use the same capabilityMatcher, defined by the registry.",
+    description = "<String> class name : a class implementing the CapabilityMatcher interface. Specifies the logic the hub will follow to define whether a request can be assigned to a node. For example, if you want to have the matching process use regular expressions instead of exact match when specifying browser version. ALL nodes of a grid ecosystem would then use the same capabilityMatcher, as defined here. Default is org.openqa.grid.internal.utils.DefaultCapabilityMatcher",
     converter = CapabilityMatcherString.class
   )
   public CapabilityMatcher capabilityMatcher = new DefaultCapabilityMatcher();
 
   @Parameter(
     names = "-newSessionWaitTimeout",
-    description = "<Integer> milliseconds. Default to no timeout ( -1 ) the time in ms after which a new test waiting for a node to become available will time out.When that happens, the test will throw an exception before starting a browser."
+    description = "<Integer> in ms : The time after which a new test waiting for a node to become available will time out. When that happens, the test will throw an exception before attempting to start a browser. Defaults to no timeout ( -1 )"
   )
   public Integer newSessionWaitTimeout = -1;
 
   @Parameter(
     names = "-prioritizer",
-    description = "a class implementing the Prioritizer interface. Default to null ( no priority = FIFO ).Specify a custom prioritizer if you want to sort the order new session requests are processed when there is a queue.",
+    description = "<String> class name : a class implementing the Prioritizer interface. Specify a custom Prioritizer if you want to sort the order in which new session requests are processed when there is a queue. Default to null ( no priority = FIFO )",
     converter = PrioritizerString.class
   )
   public Prioritizer prioritizer = null;
 
   @Parameter(
     names = "-throwOnCapabilityNotPresent",
-    description = "<true | false> default to true. If true, the hub will reject test requests right away if no proxy is currently registered that can host that capability.Set it to false to have the request queued until a node supporting the capability is added to the grid."
+    description = "<Boolean> true or false : If true, the hub will reject all test requests if no compatible proxy is currently registered. If set to false, the request will queue until a node supporting the capability is registered with the grid. Default is true"
   )
   public Boolean throwOnCapabilityNotPresent = true;
 
@@ -103,7 +103,7 @@ public Prioritizer convert(String prioritizerClass) {
       try {
         return (Prioritizer) Class.forName(prioritizerClass).newInstance();
       } catch (Throwable e) {
-        throw new GridConfigurationException("Error creating the prioritize from class " +
+        throw new GridConfigurationException("Error creating Prioritizer from class " +
                                              prioritizerClass + " : " + e.getMessage(), e);
       }
     }
@@ -115,7 +115,7 @@ public CapabilityMatcher convert(String capabilityMatcherClass) {
       try {
         return (CapabilityMatcher) Class.forName(capabilityMatcherClass).newInstance();
       } catch (Throwable e) {
-        throw new GridConfigurationException("Error creating the prioritize from class " +
+        throw new GridConfigurationException("Error creating Prioritizer from class " +
                                              capabilityMatcherClass + " : " + e.getMessage(), e);
       }
     }

java/server/src/org/openqa/grid/internal/utils/configuration/GridNodeConfiguration.java

@@ -30,7 +30,7 @@ public class GridNodeConfiguration extends GridConfiguration {
 
   @Parameter(
     names = "-id",
-    description = "unique identifier for the node, not required and grid will set this to the remoteHost"
+    description = "<String> : unique identifier for the node. Not required--by default, grid will use the url of the remoteHost"
   )
   public String id;
 
@@ -39,74 +39,74 @@ public class GridNodeConfiguration extends GridConfiguration {
 
   @Parameter(
     names = "-browser",
-    description = "comma separated capability values. Example: -browser browserName=firefox,platform=linux -browser browserName=chrome,platform=linux",
+    description = "<String> : comma separated Capability values. Example: -browser browserName=firefox,platform=linux -browser browserName=chrome,platform=linux",
     converter = DesiredCapabilityConverter.class
   )
   public List<DesiredCapabilities> browser;
 
   @Parameter(
     names = "-downPollingLimit",
-    description = "<Integer> node is marked as down after downPollingLimit alive checks."
+    description = "<Integer> : node is marked as \"down\" if the node hasn't responded after the number of checks specified in [downPollingLimit]. Default is 2"
   )
   public Integer downPollingLimit;
 
   @Parameter(
     names = "-hub",
-    description = "<http://localhost:4444/grid/register> : the url that will be used to post the registration request. This option takes precedence over -hubHost and -hubPort options."
+    description = "<String> (e.g. http://localhost:4444/grid/register) : the url that will be used to post the registration request. This option takes precedence over -hubHost and -hubPort options"
   )
   public String hub;
 
   @Parameter(
     names = "-hubHost",
-    description = "<IP | hostname> : the host address of a hub the registration request should be sent to. Default to localhost. Option -hub takes precedence over this option."
+    description = "<String> IP or hostname : the host address of the hub we're attempting to register with. If \"role\" is set to [hub], this option will be ignored. Default is localhost"
   )
   String hubHost;
 
   @Parameter(
     names = "-hubPort",
-    description = "<Integer> : the port listened by a hub the registration request should be sent to. Default to 4444. Option -hub takes precedence over this option."
+    description = "<Integer> : the port of the hub we're attempting to register with. If \"role\" is set to [hub], this option will be ignored. Default to 4444"
   )
   Integer hubPort;
 
   @Parameter(
     names = "-nodeConfig",
-    description = "<file> json configuration file for the node, overrides default values."
+    description = "<String> filename : JSON configuration file for the node. Overrides default values"
   )
   public String nodeConfigFile;
 
   @Parameter(
     names = "-nodePolling",
-    description = "<Integer> in ms. Interval between alive checks of node how often the hub checks if the node is still alive."
+    description = "<Integer> in ms : specifies how often the hub will poll to see if the node is still responding"
   )
   public Integer nodePolling;
 
   @Parameter(
     names = "-nodeStatusCheckTimeout",
-    description = "<Integer> in ms. Connection and socket timeout which is used for node alive check."
+    description = "<Integer> in ms : connection/socket timeout, used for node \"nodePolling\" check"
   )
   public Integer nodeStatusCheckTimeout;
 
   @Parameter(
     names = "-proxy",
-    description = "<String> the class that will be used to represent the node. By default org.openqa.grid.selenium.proxy.DefaultRemoteProxy."
+    description = "<String> : the class used to represent the node proxy. Default is [org.openqa.grid.selenium.proxy.DefaultRemoteProxy]"
   )
   public String proxy;
 
   @Parameter(
     names = "-register",
-    description = "include this command line option if you want the node to automatically re-register itself with a grid hub if the hub becomes unavailable. Default is disabled."
+    description = "if specified, node will attempt to re-register itself automatically with its known grid hub if the hub becomes unavailable. Default is disabled"
   )
   public Boolean register;
 
   @Parameter(
     names = "-registerCycle",
-    description = "<Integer> how often in ms the node will try to register itself again.Allow to restart the hub without having to restart the nodes."
+    description = "<Integer> in ms : specifies how often the node will try to register itself again. Allows administrator to restart the hub without restarting (or risk orphaning) registered nodes. Must be specified with the \"-register\" option"
   )
   public Integer registerCycle;
 
   @Parameter(
     names = "-unregisterIfStillDownAfter",
-    description = "<Integer> in ms. If the node remains down for more than unregisterIfStillDownAfter millisec, it will disappear from the hub.Default is 1min."
+    description = "<Integer> in ms : if the node remains down for more than [unregisterIfStillDownAfter] ms, it will step attempting to re-register from the hub. Default is 6000 (1 minute)"
   )
   public Integer unregisterIfStillDownAfter;
 

java/server/src/org/openqa/grid/internal/utils/configuration/StandaloneConfiguration.java

@@ -29,58 +29,63 @@ public class StandaloneConfiguration {
 
   @Parameter(
     names = "-browserTimeout",
-    description = "Number of seconds a browser is allowed to hang (0 means indefinite) while a command is running (example: driver.get(url)). If set, must be greater than or equal to 60. When the timeout is reached while a command is processing, the session will quit.")
+    description = "<Integer> in seconds : number of seconds a browser session is allowed to hang (0 means indefinite) while a WebDriver command is running (example: driver.get(url)). If the timeout is reached while a WebDriver command is still processing, the session will quit. Minimum value is 60. Default is 0"
+  )
   public Integer browserTimeout;
 
   @Parameter(
     names = "-debug",
-    description = "<Boolean> to enable LogLevel.FINE"
+    description = "<Boolean> : enables LogLevel.FINE. Default is false (if omitted)"
   )
   public boolean debug;
 
   @Parameter(
     names = {"--help", "-help", "-h"},
     help = true,
     hidden = true,
-    description = "This help.")
+    description = "Displays this help"
+  )
   public boolean help;
 
   @Parameter(
     names = "-jettyThreads",
-    hidden = true)
+    hidden = true
+  )
   public Integer jettyThreads;
 
   @Parameter(
     names = "-log",
-    description = "The filename to use for logging. Default value is null and indicates logging to STDOUT."
+    description = "<String> filename : the filename to use for logging. If omitted, will log to STDOUT"
   )
   public String log;
 
   @Parameter(
     names = "-logLongForm",
-    description = "if no log is specified, logLongForm can be set to enable longForm output to STDOUT. Default is false"
+    description = "<Boolean> : if specified, all log statements (including to log file from \"log\" parameter) will include the Thread ID"
   )
   public boolean logLongForm;
 
   @Parameter(
     names = {"-port"},
-    description = "The port number the selenium server should use. Default's to 4444. When role is a grid node default is 5555.")
+    description = "<Integer> : the port number the server will use. Defaults to [4444]. When \"role\" is a set to [node], default is [5555]"
+  )
   public Integer port;
 
   @Parameter(
     names = "-role",
-    description = "server role to run as. Options are hub, node, standalone. Default is standalone"
+    description = "<String> options are [hub], [node], or [standalone] : Default is [standalone]"
   )
-  public String role;
+  public String role = "standalone";
 
   @Parameter(
     names = {"-timeout", "-sessionTimeout"},
-    description = "<Integer> the timeout in seconds before the hub automatically ends a test that hasn't had any activity in the last X seconds. The browser will be released for another test to use. This typically takes care of the client crashes. For grid hub/node roles, CleanUpCycle must also be set. Default is 1800 (30 minutes)")
+    description = "<Integer> in seconds : Specifies the timeout before the hub automatically kills a session that hasn't had any activity in the last X seconds. The test slot will then be released for another test to use. This is typically used to take care of client crashes. For grid hub/node roles, cleanUpCycle must also be set. Default is 1800 (30 minutes)"
+  )
   public Integer timeout = 1800;
 
   @Parameter(
     names = {"-avoidProxy"},
-    description = "DO NOT USE. Hack to allow selenium 3.0 server run in saucelabs"
+    description = "DO NOT USE. Hack to allow selenium 3.0 server run in SauceLabs"
   )
   private Boolean avoidProxy;