doc improvement.

git-svn-id: https://hudson.dev.java.net/svn/hudson/trunk/hudson/main@21450 71c3de6d-444a-0410-be80-ed276b4c234a

core/src/main/java/hudson/cli/CLICommand.java

@@ -56,6 +56,9 @@ import java.util.Locale;
  * calls {@link #main(List, Locale, InputStream, PrintStream, PrintStream)} method.
  *
  * <h2>Note for CLI command implementor</h2>
+ * Start with <a href="http://wiki.hudson-ci.org/display/HUDSON/Writing+CLI+commands">this document</a>
+ * to get the general idea of CLI.
+ *
  * <ul>
  * <li>
  * Put {@link Extension} on your implementation to have it discovered by Hudson.

core/src/main/java/hudson/cli/declarative/CLIMethod.java

@@ -24,7 +24,9 @@
 package hudson.cli.declarative;
 
 import hudson.cli.CLICommand;
+import hudson.util.ListBoxModel.Option;
 import org.jvnet.hudson.annotation_indexer.Indexed;
+import org.kohsuke.args4j.Argument;
 
 import java.lang.annotation.Documented;
 import static java.lang.annotation.ElementType.METHOD;
@@ -37,8 +39,19 @@ import java.lang.annotation.Target;
  *
  * <p>
  * You need to have <tt>Messages.properties</tt> in the same package with the
- * <tt>CLI.command-name.shortDescription</tt> key to describe the command.
- * This is used for {@link CLICommand#getShortDescription()}.
+ * <tt>CLI.<i>command-name</i>.shortDescription</tt> key to describe the command.
+ * This is used for the same purpose as {@link CLICommand#getShortDescription()}.
+ *
+ * <p>
+ * If you put a {@link CLIMethod} on an instance method (as opposed to a static method),
+ * you need a corresponding {@linkplain CLIResolver CLI resolver method}.
+ *
+ * <p>
+ * A CLI method can have its parameters annotated with {@link Option} and {@link Argument},
+ * to receive parameter/argument injections.
+ *
+ * <p>
+ * A CLI method needs to be public.
  *
  * @author Kohsuke Kawaguchi
  * @see CLICommand

core/src/main/java/hudson/cli/declarative/CLIResolver.java

@@ -38,7 +38,21 @@ import java.lang.annotation.Target;
  * to an instance whose {@link CLIMethod} is invoked for the final processing.
  *
  * <p>
- * The resolver method shall never return null --- it should instead indicate a failure by throwing
+ * A resolver method must be static. Hudson uses its return
+ * type to pick the resolver method to use, of all the resolver methods it discovers. That is,
+ * if Hudson is looking to find an instance of type <tt>T</tt> for the current command, it first
+ * looks for the resolver method whose return type is <tt>T</tt>, then it checks for the base type of <tt>T</tt>,
+ * and so on.
+ *
+ * <p>
+ * By convention, we encourage the resolver method to be declared in the type it returns, but this is not a requirement.
+ *
+ * <p>
+ * Parameters of the resolver method receives the same parameter/argument injections that {@link CLIMethod}s receive.
+ * Parameters and arguments consumed by the resolver will not be visible to {@link CLIMethod}s.
+ *
+ * <p>
+ * The resolver method shall never return null &mdash; it should instead indicate a failure by throwing
  * {@link CmdLineException}.
  *
  * @author Kohsuke Kawaguchi