[Japi-cvs] SF.net SVN: japi:[1392] libs/argparser/trunk/src/prj/net/sf/japi/io/args

[<chr...@us...>]

Revision: 1392
          http://japi.svn.sourceforge.net/japi/?rev=1392&view=rev
Author:   christianhujer
Date:     2009-10-26 05:54:27 +0000 (Mon, 26 Oct 2009)

Log Message:
-----------
Improve documentation.

Modified Paths:
--------------
    libs/argparser/trunk/src/prj/net/sf/japi/io/args/ArgParser.java
    libs/argparser/trunk/src/prj/net/sf/japi/io/args/Option.java
    libs/argparser/trunk/src/prj/net/sf/japi/io/args/converter/ConverterRegistry.java

Modified: libs/argparser/trunk/src/prj/net/sf/japi/io/args/ArgParser.java
===================================================================
--- libs/argparser/trunk/src/prj/net/sf/japi/io/args/ArgParser.java	2009-10-05 23:51:41 UTC (rev 1391)
+++ libs/argparser/trunk/src/prj/net/sf/japi/io/args/ArgParser.java	2009-10-26 05:54:27 UTC (rev 1392)
@@ -38,10 +38,26 @@
 
 /**
  * Parser for command line arguments.
+ * <p>
+ * The most popular usage is by extending {@link BasicCommand} and invoking {@link #simpleParseAndRun(Command, String[])}, like this:
+ * {@listing java import net.sf.japi.io.args.*;
+ * public class HelloCommand extends BasicCommand {
+ *     public static void main(final String... args) {
+ *         ArgParser.simpleParseAndRun(new HelloCommand(), args);
+ *     }
+ *     public void run(final List<String> args) throws Exception {
+ *         System.out.println("Hello, world!");
+ *     }
+ * }}
  *
  * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  * @since 0.2
  *
+ * @see net.sf.japi.io.args
+ * @see Command
+ * @see BasicCommand
+ * @see ConverterRegistry
+ *
  * @todo better handling of boolean arguments
  * @todo Handling of - for STDIN as input argument filestream
  * @todo automatic printout of default values if property getter available.

Modified: libs/argparser/trunk/src/prj/net/sf/japi/io/args/Option.java
===================================================================
--- libs/argparser/trunk/src/prj/net/sf/japi/io/args/Option.java	2009-10-05 23:51:41 UTC (rev 1391)
+++ libs/argparser/trunk/src/prj/net/sf/japi/io/args/Option.java	2009-10-26 05:54:27 UTC (rev 1392)
@@ -26,8 +26,36 @@
 
 /**
  * Annotation to mark a method as command argument method.
+ * <p>
+ * Examples:
+ * {@listing java @Option("r")
+ * public void recurse() {
+ *     recursive = true;
+ * }
+ *
+ * @Option("recursive")
+ * public void setRecursive(final boolean recursive) {
+ *     this.recursive = recursive;
+ * }
+ *
+ * @Option(type = OptionType.TERMINAL, value = {"listEncodings"})
+ * public void listEncodings() {
+ *     for (final String encoding : encodings) {
+ *          System.out.println(encoding);
+ *     }
+ * }
+ * }
+ * The commands derived from {@link CommandWithHelp} (incl. {@link BasicCommand}) support reading help descriptions from {@link ResourceBundle}s.
+ * For that, the package of the command implementation needs a {Resourcebundle} with the same basename as the command class.
+ * A properties file which matches above example could look like this:
+ * {@listing properties recurse=Recurse into subdirectories.
+ * setRecursive=Set whether or not to recurse into subdirectories.
+ * listEncodings=List the encodings and exit.}
+ *
  * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  * @since 0.2
+ *
+ * @see OptionType for the supported types of options.
  */
 @Documented
 @Retention(RUNTIME)

Modified: libs/argparser/trunk/src/prj/net/sf/japi/io/args/converter/ConverterRegistry.java
===================================================================
--- libs/argparser/trunk/src/prj/net/sf/japi/io/args/converter/ConverterRegistry.java	2009-10-05 23:51:41 UTC (rev 1391)
+++ libs/argparser/trunk/src/prj/net/sf/japi/io/args/converter/ConverterRegistry.java	2009-10-26 05:54:27 UTC (rev 1392)
@@ -27,9 +27,9 @@
 import org.jetbrains.annotations.Nullable;
 
 /**
- * Registry for Converters.
+ * Registry for {@link Converter}s.
  * <p>
- * Per default, the following are supported:
+ * Per default, the following {@link Converter}s are supported:
  * <ul>
  *  <li>String (this is an identity conversion)</li>
  *  <li>All primitive types (boolean, byte, short, int, long, char, float, double).</li>
@@ -37,6 +37,7 @@
  *  <li>All types which have a public constructor that takes a single String argument.</li>
  *  <li>All Enums.</li>
  * </ul>
+ * The ConverterRegistry uses the {@link ServiceLoader ServiceLoader} to find additional {@link Converter}s.
  * @author <a href="mailto:ch...@ri...">Christian Hujer</a>
  * @since 0.2
  */
@@ -128,6 +129,7 @@
      */
     public <T> void register(@NotNull final Converter<T> converter) {
         converters.put(converter.getTargetClass(), converter);
+        //noinspection NestedAssignment
         for (Class<?> superClass = converter.getTargetClass(); (superClass = superClass.getSuperclass()) != null;) {
             if (!converters.containsKey(superClass)) {
                 converters.put(superClass, converter);


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.