fix(javadoc): phase 9 — CMF enum, CLIContext/CLI/CLISubSystem expansion, SsmActionBase

- CMF.java: add inline comments to all 163 undocumented enum constants
- CLIContext: expand all inline /** @... */ javadocs to multi-line with descriptions
  (getActiveSubSystem, setActiveSubSystem, isStopped, setStopped, getReader, setReader,
  getOutputStream, getErrorStream, getInputStream, getUserData, isInteractive, getCLI,
  printUserData, printThrowable, printLoggeable, print, println, confirm, readSecurely,
  builder(), Builder class + all 6 builder methods)
- CLI: expand all inline javadocs to multi-line with descriptions
  (running, getCompletionPrefixes, getQ2, isInteractive, getReader, exec(2 overloads),
  buildTerminal, constructor javadocs)
- CLICommandInterface: expand all inline javadocs
- CLISubSystem: expand getPrompt() and getCompletionPrefixes() javadocs
- CLIPrefixedClassNameCompleter: expand constructor javadoc
- SsmActionBase: add constructor + documented checkUsage/doCommand abstract methods
- ChannelAdaptor: expand grabSpace() inline javadoc
- IRC.java: expand getIRC/isSuccess/isInhibit javadocs

Author: ar-agt

jpos/src/main/java/org/jpos/q2/CLI.java

@@ -78,7 +78,10 @@ public CLI(Q2 q2, InputStream in, OutputStream rawout, String line, boolean keep
         initCmdInterface(getCompletionPrefixes(), mainHistory);
     }
 
-    /** @return true if this CLI is still running */
+    /**
+     * Returns true if this CLI is still running.
+     * @return true if running
+     */
     protected boolean running() {
         return getQ2() == null || getQ2().running();
     }
@@ -89,7 +92,10 @@ protected void markStopped() { }
     /** Called when the CLI is starting; subclasses may override. */
     protected void markStarted() { }
 
-    /** @return array of command prefixes for tab-completion */
+    /**
+     * Returns command prefixes registered for tab-completion.
+     * @return array of command prefixes
+     */
     protected String[] getCompletionPrefixes() {
         return new String[] {"org.jpos.q2.cli." };
     }
@@ -197,22 +203,33 @@ public void run() {
         handleExit();
     }
 
-    /** @return the Q2 instance this CLI is attached to */
+    /**
+     * Returns the Q2 instance this CLI is attached to.
+     * @return the Q2 instance
+     */
     public Q2 getQ2() {
         return q2;
     }
 
-    /** @return true if this is an interactive session */
+    /**
+     * Returns true if this CLI session is interactive.
+     * @return true if interactive
+     */
     public boolean isInteractive() {
         return interactive;
     }
 
-    /** @return the JLine3 LineReader for this session */
+    /**
+     * Returns the JLine3 LineReader for this session.
+     * @return the LineReader
+     */
     public LineReader getReader() {
         return reader;
     }
 
-    /** @param in input stream
+    /**
+     * Executes a CLI command with the given I/O streams.
+     * @param in input stream
      * @param out output stream
      * @param command command to execute
      * @throws Exception on execution failure
@@ -223,7 +240,9 @@ public static void exec (InputStream in, OutputStream out, String command) throw
         cli.stop();
     }
 
-    /** @param command command string to execute
+    /**
+     * Executes a CLI command and captures its output as a string.
+     * @param command command string to execute
      * @return captured output
      * @throws Exception on execution failure
      */
@@ -233,9 +252,11 @@ public static String exec (String command) throws Exception {
         return out.toString();
     }
 
-    /** @param in input stream
+    /**
+     * Builds a JLine3 Terminal for this session.
+     * @param in input stream
      * @param out output stream
-     * @return a JLine3 Terminal for this session
+     * @return the Terminal
      * @throws IOException on I/O failure
      */
     protected Terminal buildTerminal (InputStream in, OutputStream out) throws IOException {

jpos/src/main/java/org/jpos/q2/CLICommandInterface.java

@@ -32,22 +32,33 @@ public class CLICommandInterface {
     CLIContext ctx;
     List<String> prefixes = new ArrayList<String>();
 
-    /** @return the list of registered command prefixes */
+    /**
+     * Returns the list of registered command prefixes.
+     * @return command prefix list
+     */
     public List<String> getPrefixes() {
         return prefixes;
     }
 
-    /** @param ctx the CLI context for this interface */
+    /**
+     * Creates a CLICommandInterface for the given context.
+     * @param ctx the CLI context
+     */
     public CLICommandInterface(CLIContext ctx) {
         this.ctx = ctx;
     }
 
-    /** @param prefix a command prefix to register */
+    /**
+     * Registers a command prefix.
+     * @param prefix the prefix to add
+     */
     public void addPrefix(String prefix) {
         prefixes.add(prefix);
     }
 
-    /** @param line the full command line to execute
+    /**
+     * Executes the given command line.
+     * @param line the full command line
      * @throws IOException on I/O failure
      */
     public void execCommand(String line) throws IOException {
@@ -98,7 +109,9 @@ private Object getCommand(String className) throws ClassNotFoundException, Insta
         return cl.loadClass(className).newInstance();
     }
 
-    /** @param line the full command line to parse
+    /**
+     * Parses a command line into tokens.
+     * @param line the full command line
      * @return tokens: [prefix, command, args...]
      * @throws IOException on I/O failure
      */

jpos/src/main/java/org/jpos/q2/CLIContext.java

@@ -48,12 +48,18 @@ private CLIContext(CLI cli, OutputStream out, OutputStream err, InputStream in,
         this.userData = userData;
     }
 
-    /** @return the name of the active CLI sub-system, or null */
+    /**
+     * Returns the name of the active CLI sub-system.
+     * @return the active sub-system name, or null
+     */
     public String getActiveSubSystem() {
         return activeSubSystem;
     }
 
-    /** @param subSystem the name of the new active sub-system */
+    /**
+     * Sets the active CLI sub-system by name.
+     * @param subSystem the name of the new active sub-system
+     */
     public void setActiveSubSystem(String subSystem) {
         String activeSubSystem = getActiveSubSystem();
         if (subSystem == null && activeSubSystem != null) {
@@ -62,52 +68,82 @@ public void setActiveSubSystem(String subSystem) {
         this.activeSubSystem = subSystem;
     }
 
-    /** @return true if this CLI session has been stopped */
+    /**
+     * Returns true if this CLI session has been stopped.
+     * @return true if stopped
+     */
     public boolean isStopped() {
         return stopped;
     }
 
-    /** @param stopped true to mark this session as stopped */
+    /**
+     * Marks this CLI session as stopped.
+     * @param stopped true to stop
+     */
     public void setStopped(boolean stopped) {
         this.stopped = stopped;
     }
 
-    /** @return the JLine3 LineReader for interactive input */
+    /**
+     * Returns the JLine3 LineReader for interactive input.
+     * @return the LineReader
+     */
     public LineReader getReader() {
         return reader;
     }
 
-    /** @param reader the JLine3 LineReader */
+    /**
+     * Sets the JLine3 LineReader.
+     * @param reader the LineReader
+     */
     public void setReader(LineReader reader) {
         this.reader = reader;
     }
 
-    /** @return the standard output stream for this session */
+    /**
+     * Returns the standard output stream for this session.
+     * @return the output stream
+     */
     public OutputStream getOutputStream() {
         return out;
     }
 
-    /** @return the error stream for this session */
+    /**
+     * Returns the error stream for this session.
+     * @return the error stream
+     */
     public OutputStream getErrorStream() {
         return err;
     }
 
-    /** @return the input stream for this session */
+    /**
+     * Returns the input stream for this session.
+     * @return the input stream
+     */
     public InputStream getInputStream() {
         return in;
     }
 
-    /** @return mutable user-data map for sharing state across CLI commands */
+    /**
+     * Returns the mutable user-data map for sharing state across CLI commands.
+     * @return user data map
+     */
     public Map<Object,Object> getUserData() {
         return userData;
     }
 
-    /** @return true if this session is interactive (has a LineReader) */
+    /**
+     * Returns true if this session is interactive (has a LineReader).
+     * @return true if interactive
+     */
     public boolean isInteractive() {
         return cli.isInteractive();
     }
 
-    /** @return the CLI instance managing this context */
+    /**
+     * Returns the CLI instance managing this context.
+     * @return the CLI
+     */
     public CLI getCLI() {
         return cli;
     }
@@ -120,14 +156,19 @@ public void printUserData() {
         });
     }
 
-    /** @param t the throwable to print (stack trace goes to error stream) */
+    /**
+     * Prints a throwable stack trace to the error stream.
+     * @param t the throwable to print
+     */
     public void printThrowable(Throwable t) {
         ByteArrayOutputStream baos = new ByteArrayOutputStream();
         t.printStackTrace(new PrintStream(baos));
         println (baos.toString());
     }
 
-    /** @param l the Loggeable to dump
+    /**
+     * Dumps a Loggeable to the output stream.
+     * @param l the Loggeable to dump
      * @param indent indentation prefix
      */
     public void printLoggeable(Loggeable l, String indent) {
@@ -136,7 +177,10 @@ public void printLoggeable(Loggeable l, String indent) {
         println (baos.toString());
     }
 
-    /** @param s string to print (no trailing newline) */
+    /**
+     * Prints a string to the output stream (no trailing newline).
+     * @param s the string to print
+     */
     public void print(String s) {
         if (isInteractive()) {
             PrintWriter writer = getReader().getTerminal().writer();
@@ -153,26 +197,36 @@ public void print(String s) {
         }
     }
 
-    /** @param s string to print followed by a newline */
+    /**
+     * Prints a string to the output stream followed by a newline.
+     * @param s the string to print
+     */
     public void println(String s)  {
         print (s + System.getProperty("line.separator"));
     }
 
-    /** @param prompt the confirmation prompt
+    /**
+     * Prompts the user for confirmation.
+     * @param prompt the confirmation prompt
      * @return true if user confirmed
      */
     public boolean confirm(String prompt) {
         return "yes".equalsIgnoreCase(getReader().readLine(prompt));
     }
 
-    /** @param prompt the prompt to display
-     * @return the input string, read without echoing
+    /**
+     * Reads a string from the user without echoing (e.g. for passwords).
+     * @param prompt the prompt to display
+     * @return the input string
      */
     public String readSecurely(String prompt) {
         return getReader().readLine(prompt, '*');
     }
 
-    /** @return a new Builder for constructing a CLIContext */
+    /**
+     * Returns a new Builder for constructing a CLIContext.
+     * @return a new Builder
+     */
     public static Builder builder() {
         return new Builder();
     }
@@ -186,37 +240,60 @@ public static class Builder {
         CLI cli;
         private Builder () { }
 
-        /** @param out the standard output stream @return this */
+        /**
+         * Sets the standard output stream.
+         * @param out the standard output stream
+         * @return this
+         */
         public Builder out (OutputStream out) {
             this.out = out;
             return this;
         }
 
-        /** @param err the error stream @return this */
+        /**
+         * Sets the error stream.
+         * @param err the error stream
+         * @return this
+         */
         public Builder err (OutputStream err) {
             this.err = err;
             return this;
         }
 
-        /** @param in the input stream @return this */
+        /**
+         * Sets the input stream.
+         * @param in the input stream
+         * @return this
+         */
         public Builder in (InputStream in) {
             this.in = in;
             return this;
         }
 
-        /** @param reader the JLine3 LineReader @return this */
+        /**
+         * Sets the JLine3 LineReader.
+         * @param reader the LineReader
+         * @return this
+         */
         public Builder reader (LineReader reader) {
             this.reader = reader;
             return this;
         }
 
-        /** @param cli the CLI instance @return this */
+        /**
+         * Sets the CLI instance.
+         * @param cli the CLI
+         * @return this
+         */
         public Builder cli (CLI cli) {
             this.cli = cli;
             return this;
         }
 
-        /** @return the constructed CLIContext */
+        /**
+         * Builds and returns the CLIContext.
+         * @return the constructed CLIContext
+         */
         public CLIContext build() {
             if (reader != null) {
                 if (out == null)