From c5efb6f40e7c20ee1cb5fe965719c9089aea8809 Mon Sep 17 00:00:00 2001 From: Mark DePristo Date: Thu, 18 Aug 2011 21:39:11 -0400 Subject: [PATCH] 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? --- .../sting/commandline/Advanced.java | 40 +++++++++++++++++++ .../sting/commandline/ArgumentSource.java | 15 ++++++- .../sting/commandline/ParsingEngine.java | 2 +- .../help/GenericDocumentationHandler.java | 2 + 4 files changed, 57 insertions(+), 2 deletions(-) create mode 100644 public/java/src/org/broadinstitute/sting/commandline/Advanced.java diff --git a/public/java/src/org/broadinstitute/sting/commandline/Advanced.java b/public/java/src/org/broadinstitute/sting/commandline/Advanced.java new file mode 100644 index 000000000..7aeefe261 --- /dev/null +++ b/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 { +} diff --git a/public/java/src/org/broadinstitute/sting/commandline/ArgumentSource.java b/public/java/src/org/broadinstitute/sting/commandline/ArgumentSource.java index e0e2ac378..3e149b0c6 100644 --- a/public/java/src/org/broadinstitute/sting/commandline/ArgumentSource.java +++ b/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 { /** * 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()); + } } diff --git a/public/java/src/org/broadinstitute/sting/commandline/ParsingEngine.java b/public/java/src/org/broadinstitute/sting/commandline/ParsingEngine.java index fbf8c6516..12b454f4f 100755 --- a/public/java/src/org/broadinstitute/sting/commandline/ParsingEngine.java +++ b/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 extractArgumentBindings(Object obj, Class sourceClass, Field[] parentFields) { - Map bindings = new LinkedHashMap(); + Map bindings = new TreeMap(); while( sourceClass != null ) { Field[] fields = sourceClass.getDeclaredFields(); diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java index 86f72428a..fe08e5979 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java @@ -116,6 +116,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { args.put("all", new ArrayList()); args.put("required", new ArrayList()); args.put("optional", new ArrayList()); + args.put("advanced", new ArrayList()); args.put("hidden", new ArrayList()); args.put("depreciated", new ArrayList()); 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";