Usability improvements to GATKDocs

-- ArgumentSources are now sorted by case insensitive names, so arguments are shown in alphabetical order (Ryan)
-- @Advanced annotation can be used to indicate that an argument is an advanced option and should be visually deemphasized in the GATKs.  There's now an advanced section.  Mauricio or Ryan -- could you figure out how to make this section less prominent in the style.css?

public/java/src/org/broadinstitute/sting/commandline/Advanced.java

@@ -0,0 +1,40 @@
+/*
+ * Copyright (c) 2011, The Broad Institute
+ *
+ * Permission is hereby granted, free of charge, to any person
+ * obtaining a copy of this software and associated documentation
+ * files (the "Software"), to deal in the Software without
+ * restriction, including without limitation the rights to use,
+ * copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the
+ * Software is furnished to do so, subject to the following
+ * conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+ * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+ * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+ * OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+package org.broadinstitute.sting.commandline;
+
+import java.lang.annotation.*;
+
+/**
+ * Indicates that a walker argument should is considered an advanced option.
+ *
+ * @author Mark DePristo
+ * @version 0.1
+ */
+@Documented
+@Inherited
+@Retention(RetentionPolicy.RUNTIME)
+@Target({ElementType.TYPE,ElementType.FIELD})
+public @interface Advanced {
+}

public/java/src/org/broadinstitute/sting/commandline/ArgumentSource.java

@@ -39,7 +39,7 @@ import java.util.List;
  * @author mhanna
  * @version 0.1
  */
-public class ArgumentSource {
+public class ArgumentSource implements Comparable<ArgumentSource> {
     /**
      * Field into which to inject command-line arguments.
      */
@@ -151,6 +151,14 @@ public class ArgumentSource {
         return field.isAnnotationPresent(Hidden.class) || field.isAnnotationPresent(Deprecated.class);
     }
 
+    /**
+     * Is the given argument considered an advanced option when displaying on the command-line argument system.
+     * @return True if so.  False otherwise.
+     */
+    public boolean isAdvanced() {
+        return field.isAnnotationPresent(Advanced.class);
+    }
+
     /**
      * Is this command-line argument dependent on some primitive argument types?
      * @return True if this command-line argument depends on other arguments; false otherwise.
@@ -208,4 +216,9 @@ public class ArgumentSource {
     public String toString() {
         return field.getDeclaringClass().getSimpleName() + ": " + field.getName();
     }
+
+    @Override
+    public int compareTo(final ArgumentSource argumentSource) {
+        return field.getName().toLowerCase().compareTo(argumentSource.field.getName().toLowerCase());
+    }
 }

public/java/src/org/broadinstitute/sting/commandline/ParsingEngine.java

@@ -451,7 +451,7 @@ public class ParsingEngine {
      * @return A map of sources associated with this object and its aggregated objects and bindings to their bindings values
      */
     private Map<ArgumentSource, Object> extractArgumentBindings(Object obj, Class sourceClass, Field[] parentFields) {
-        Map<ArgumentSource, Object> bindings = new LinkedHashMap<ArgumentSource, Object>();
+        Map<ArgumentSource, Object> bindings = new TreeMap<ArgumentSource, Object>();
 
         while( sourceClass != null ) {
             Field[] fields = sourceClass.getDeclaredFields();

public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java

@@ -116,6 +116,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
         args.put("all", new ArrayList<Object>());
         args.put("required", new ArrayList<Object>());
         args.put("optional", new ArrayList<Object>());
+        args.put("advanced", new ArrayList<Object>());
         args.put("hidden", new ArrayList<Object>());
         args.put("depreciated", new ArrayList<Object>());
         try {
@@ -127,6 +128,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
                     logger.debug(String.format("Processing %s", argumentSource));
                     String kind = "optional";
                     if ( argumentSource.isRequired() ) kind = "required";
+                    else if ( argumentSource.isAdvanced() ) kind = "advanced";
                     else if ( argumentSource.isHidden() ) kind = "hidden";
                     else if ( argumentSource.isDeprecated() ) kind = "depreciated";