--- a/common/core/src/main/java/com/redhat/thermostat/common/cli/CliCommandOption.java	Fri May 27 10:43:08 2016 -0400
+++ b/common/core/src/main/java/com/redhat/thermostat/common/cli/CliCommandOption.java	Fri May 27 12:01:26 2016 -0400
@@ -36,8 +36,18 @@
 
 package com.redhat.thermostat.common.cli;
 
+/**
+ * Used for describing command line flags or options.
+ *
+ * Example: in "foo-command --help", a CliCommandOption could be used to describe "--help".
+ */
 public class CliCommandOption {
 
+    /**
+     * Special constant for use with {@link CompleterService}, which indicates a "meta-option" which is really
+     * the first non-option argument. Use this constant if you are implementing a command which takes a
+     * non-option argument and for which you intend to provide tab completions.
+     */
     public static final CliCommandOption POSITIONAL_ARG_COMPLETION = new CliCommandOption("__NO_ARG__", "__NO_ARG__");
 
     private final String opt;
@@ -46,11 +56,18 @@
     private final String description;
     private final boolean required;
 
-    public CliCommandOption(String opt, String description) throws IllegalArgumentException {
+    private CliCommandOption(String opt, String description) {
         this(opt, null, false, description, false);
     }
 
-    public CliCommandOption(String opt, String longOpt, boolean hasArg, String description, boolean required) throws IllegalArgumentException {
+    /**
+     * @param opt the short-option, ex. in the case of "-h", this should be "h"
+     * @param longOpt the long-option, ex. in the case of "--help", this should be "help"
+     * @param hasArg defines whether or not this option expects an argument
+     * @param description a description of what the option does
+     * @param required defines whether or not this option is optional or must be included in a command invocation
+     */
+    public CliCommandOption(String opt, String longOpt, boolean hasArg, String description, boolean required) {
         this.opt = opt;
         this.longOpt = longOpt;
         this.hasArg = hasArg;

--- a/common/core/src/main/java/com/redhat/thermostat/common/cli/CompletionFinder.java	Fri May 27 10:43:08 2016 -0400
+++ b/common/core/src/main/java/com/redhat/thermostat/common/cli/CompletionFinder.java	Fri May 27 12:01:26 2016 -0400
@@ -41,10 +41,10 @@
 import java.util.List;
 
 /**
- * Intended for use with {@link TabCompleter}. Provides a list of {@link CompletionInfo}, which are displayed as
- * tab-completion results in cli/shell in certain contexts.
+ * Intended for use with {@link CompletionFinderTabCompleter}. Provides a list of {@link CompletionInfo},
+ * which is displayed as tab-completion results in Thermostat shell.
  *
- * @see TabCompleter
+ * @see CompletionFinderTabCompleter
  * @see CompleterService
  */
 @ExtensionPoint

--- a/common/core/src/main/java/com/redhat/thermostat/common/cli/CompletionFinderTabCompleter.java	Fri May 27 10:43:08 2016 -0400
+++ b/common/core/src/main/java/com/redhat/thermostat/common/cli/CompletionFinderTabCompleter.java	Fri May 27 12:01:26 2016 -0400
@@ -41,18 +41,26 @@
 import java.util.ArrayList;
 import java.util.Collections;
 import java.util.List;
+import java.util.Objects;
 
 /**
- * Provides cli/shell tab completion for various strings, ex. agentId, vmId.
+ * Provides shell tab completions as provided by {@link CompletionFinder}s.
  */
 public class CompletionFinderTabCompleter implements TabCompleter {
 
     private CompletionFinder finder;
 
+    /**
+     * Construct a new instance.
+     * @param finder the CompletionFinder which provides completion candidates. Must not be null.
+     */
     public CompletionFinderTabCompleter(CompletionFinder finder) {
-        this.finder = finder;
+        this.finder = Objects.requireNonNull(finder);
     }
 
+    /**
+     * {@inheritDoc}
+     */
     @Override
     public int complete(String buffer, int cursor, List<CharSequence> candidates) {
         List<CompletionInfo> completions = filterCompletionsWithBuffer(finder.findCompletions(), buffer);

--- a/common/core/src/main/java/com/redhat/thermostat/common/cli/CompletionInfo.java	Fri May 27 10:43:08 2016 -0400
+++ b/common/core/src/main/java/com/redhat/thermostat/common/cli/CompletionInfo.java	Fri May 27 12:01:26 2016 -0400
@@ -41,18 +41,29 @@
 import static java.util.Objects.requireNonNull;
 
 /**
- * A simple structure used for tab-completion.
+ * A simple structure used for tab-completion candidates.
  */
 public class CompletionInfo {
 
     private String actualCompletion;
     private String userVisibleText;
 
+    /**
+     * Cosntruct a CompletionInfo with a tab completion candidate as well as a descriptive label
+     * to distinguish the candidate.
+     * @param actualCompletion the text which may be tab completed
+     * @param userVisibleText a label displayed beside the completion text
+     */
     public CompletionInfo(String actualCompletion, String userVisibleText) {
         this.actualCompletion = requireNonNull(actualCompletion);
         this.userVisibleText = userVisibleText;
     }
 
+    /**
+     * Construct a CompletionInfo with a tab completion candidate, and no additional label to
+     * distinguish the candidate.
+     * @param actualCompletion the text which may be tab completed
+     */
     public CompletionInfo(String actualCompletion) {
         this(actualCompletion, null);
     }
@@ -75,6 +86,8 @@
 
     /**
      * Provides the String displayed to the user when tab-completion returns more than one possible result.
+     * This will contain the completion candidate ({@link #getActualCompletion()}), as well as the descriptive
+     * label ({@link #getUserVisibleText()}), if available.
      * @return the display String
      */
     public String getCompletionWithUserVisibleText() {

--- a/common/core/src/main/java/com/redhat/thermostat/common/cli/TabCompleter.java	Fri May 27 10:43:08 2016 -0400
+++ b/common/core/src/main/java/com/redhat/thermostat/common/cli/TabCompleter.java	Fri May 27 12:01:26 2016 -0400
@@ -38,6 +38,17 @@
 
 import java.util.List;
 
+/**
+ * Interface for tab completion providers.
+ */
 public interface TabCompleter {
+    /**
+     * Perform tab completion.
+     *
+     * @param buffer the current contents of the command line
+     * @param cursor the position of the editor cursor within the command line
+     * @param candidates out variable containing the possible completions
+     * @return -1 iff no completions are available from this TabCompleter
+     */
     int complete(String buffer, int cursor, List<CharSequence> candidates);
 }

--- a/launcher/src/main/java/com/redhat/thermostat/launcher/internal/TabCompletion.java	Fri May 27 10:43:08 2016 -0400
+++ b/launcher/src/main/java/com/redhat/thermostat/launcher/internal/TabCompletion.java	Fri May 27 12:01:26 2016 -0400
@@ -60,6 +60,11 @@
     private static final String LONG_OPTION_PREFIX = "--";
     private static final String SHORT_OPTION_PREFIX = "-";
 
+    /**
+     * Not intended to be available to plugins, only built-ins such as vmId and agentId completion.
+     * This is why reference equality is used when checking for this constant, otherwise it is too
+     * easy for plugins to "hijack" this class and offer completions for commands from other plugins.
+     */
     static final Set<String> ALL_COMMANDS_COMPLETER = Collections.singleton("ALL_COMMANDS_COMPLETER");
 
     private TreeCompleter treeCompleter;