Help command improvements

[dchambers]

No description provided.

[andy-berry-dev]

Is there a reason for this extra whitespace in the command help message?

[dchambers]

Yes, to emulate JSAP which tabulates it's help message by two characters.

[andy-berry-dev]

Should the whitespace not be in the validation step for tests rather than the configuration of the mock commands?

[dchambers]

Sorry @andyberry88, I don't understand the question. Can you explain it differently?

[andy-berry-dev]

As far as I can tell these lines are configuring mock commands that are added to the model so they can be used in tests. The third argument sets the command's help message text, instead of having a mock command object with a fixed help message. So this test is now not simulating the behaviour of a real commands help message format since the help message itself has extra whitespace rather than a utility that outputs them to the console adding the extra whitespace.

[dchambers]

@andyberry88, f995a50 makes things worse than how I had them in the first place. If I'd updated the JavaDoc for getCommandHelp() to account for my change then it would have looked like this:

/**
 * Returns a detailed help message that describes the various parameters the command
 * provides, and how they are used.
 * 
 * <p>The message must be tabulated two characters from the left so that it appears
 * correctly in the console.</p>
 * 
 * <p><b>Note:</b> This method doesn't need to be implemented if you've chosen to extend
 * {@link JSAPArgsParsingCommandPlugin}.</p>
 * 
 * @return A help message to be displayed if the command is used incorrectly
 */
public String getCommandHelp();

where this is the paragraph I've added:

 * <p>The message must be tabulated two characters from the left so that it appears
 * correctly in the console.</p>

whereas for your commit we'd need this instead:

 * <p>If you're only returning a single line message then you don't need to tabulate it,
 * but otherwise your message must be tabulated two characters from the left, so that it
 * appears correctly in the console.</p>

[dchambers]

Sorry @thecapdan, my mistake, I meant to move this back to 2 - Dev when I commented on it earlier.

[andy-berry-dev]

I've changed the help command so it correctly indents each line by at least 2 characters. We can't make any assumptions about the rest of the line. Some commands will want to output a tabbed help message where every other line is a longer description of an argument and is indented slightly more. Some commands might not want to do this and may just want all lines to be indented equally.

We should only add 2 characters at the start of line so the help message is slightly indented, the rest is up to the command plugin author.

[dchambers]

Okay, this is now somewhat of an improvement over my original commit since help commands are no longer required to indent their first line specifically for a terminal (precluding the display of the help message elsewhere), but they are still required to perform terminal specific internal indentation because we don't provide a mechanism for commands to emit tab characters that are then converted in a sensible way depending on where the message is being displayed.

Again, I'm not bothered by this because the only place we currently display messages is within the terminal, and we have access to the source code for every command plug-in ever written should we want to change this in the future.