Add a taglet to allow users to override the display name in command-line help.

git-svn-id: file:///humgen/gsa-scr1/gsa-engineering/svn_contents/trunk@2270 348d0f76-0448-11de-a6fe-93d51630548a

java/src/org/broadinstitute/sting/gatk/WalkerManager.java

@@ -35,6 +35,7 @@ import org.broadinstitute.sting.gatk.refdata.ReferenceOrderedData;
 import org.broadinstitute.sting.gatk.filters.FilterManager;
 import org.broadinstitute.sting.utils.StingException;
 import org.broadinstitute.sting.utils.PluginManager;
+import org.broadinstitute.sting.utils.doc.DisplayNameTaglet;
 import org.apache.log4j.Logger;
 import net.sf.picard.filter.SamRecordFilter;
 
@@ -92,7 +93,8 @@ public class WalkerManager extends PluginManager<Walker> {
      * @return A suitable display name for the package.
      */
     public String getPackageDisplayName(String packageName) {
-        return packageName.substring(packageName.lastIndexOf('.')+1);
+        String specifiedDisplayName = helpText.getProperty(packageName+"."+ DisplayNameTaglet.NAME);
+        return specifiedDisplayName != null ? specifiedDisplayName : packageName.substring(packageName.lastIndexOf('.')+1);
     }
 
     /**

java/src/org/broadinstitute/sting/playground/gatk/walkers/package-info.java

@@ -0,0 +1,4 @@
+/**
+ * @display.name Miscellaneous walkers (experimental)
+ */
+package org.broadinstitute.sting.playground.gatk.walkers;

java/src/org/broadinstitute/sting/utils/doc/DisplayNameTaglet.java

@@ -0,0 +1,120 @@
+package org.broadinstitute.sting.utils.doc;
+
+import com.sun.tools.doclets.Taglet;
+import com.sun.javadoc.Tag;
+
+import java.util.Map;
+
+/**
+ * Provide a display name in the help for packages
+ *
+ * @author mhanna
+ * @version 0.1
+ */
+public class DisplayNameTaglet implements Taglet {
+    /**
+     * The display name for this taglet.
+     */
+    public static final String NAME = "display.name";
+
+    /**
+     * Return the name of this custom tag.
+     */
+    public String getName() {
+        return NAME;
+    }
+
+    /**
+     * Will return false since this tag cannot be applied
+     * to a field.
+     * @return false since this tag cannot be applied to a field.
+     */
+    public boolean inField() {
+        return false;
+    }
+
+    /**
+     * Will return false since this tag cannot be applied
+     * to a constructor.
+     * @return false since this tag cannot be applied to a constructor.
+     */
+    public boolean inConstructor() {
+        return false;
+    }
+
+    /**
+     * Will return false since this tag cannot be applied
+     * to a method.
+     * @return false since this tag cannot be applied to a method.
+     */
+    public boolean inMethod() {
+        return false;
+    }
+
+    /**
+     * Will return false since overviews are always named
+     * by the <code>@WalkerName</code> tag.
+     * @return false always
+     */
+    public boolean inOverview() {
+        return false;
+    }
+
+    /**
+     * Will return true to indicate that packages can be given useful
+     * display text.
+     * @return true always
+     */
+    public boolean inPackage() {
+        return true;
+    }
+
+    /**
+     * Will return false indicating that types cannot be given
+     * alternate display names.
+     * @return false always.
+     */
+    public boolean inType() {
+        return false;
+    }
+
+    /**
+     * Will return false since <code>@todo</code>
+     * is not an inline tag.
+     * @return false since <code>@todo</code>
+     * is not an inline tag.
+     */
+
+    public boolean isInlineTag() {
+        return false;
+    }
+
+    /**
+     * Register this Taglet.
+     * @param tagletMap  the map to register this tag to.
+     */
+    public static void register(Map tagletMap) {
+       DisplayNameTaglet tag = new DisplayNameTaglet();
+       Taglet t = (Taglet)tagletMap.get(tag.getName());
+       if (t != null) {
+           tagletMap.remove(tag.getName());
+       }
+       tagletMap.put(tag.getName(), tag);
+    }
+
+    /**
+     * Create a string representation of this tag.  Since this tag is only
+     * used by the help system, don't output any HTML.
+     */
+    public String toString(Tag tag) {
+        return null;
+    }
+
+    /**
+     * Create a string representation of this tag.  Since this tag is only
+     * used by the help system, don't output any HTML.
+     */
+    public String toString(Tag[] tags) {
+        return null;
+    }
+}

java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java

@@ -1,8 +1,6 @@
 package org.broadinstitute.sting.utils.doc;
 
-import com.sun.javadoc.RootDoc;
+import com.sun.javadoc.*;
-import com.sun.javadoc.PackageDoc;
-import com.sun.javadoc.ClassDoc;
 
 import java.util.HashSet;
 import java.util.Set;
@@ -10,6 +8,8 @@ import java.util.Scanner;
 import java.io.PrintStream;
 import java.io.FileNotFoundException;
 
+import org.broadinstitute.sting.utils.StingException;
+
 /**
  * Extracts certain types of javadoc (specifically package and class descriptions) and makes them available
  * to applications at runtime.
@@ -41,17 +41,12 @@ public class HelpExtractorDoclet {
             String className = containingPackage.name().length() > 0 ?
                     String.format("%s.%s",containingPackage.name(),currentClass.name()) :
                     String.format("%s",currentClass.name());
-            String commentText = formatText(currentClass.commentText());
 
-            if(commentText.length() > 0)
+            renderHelpText(className,currentClass,out);
-                out.printf("%s=%s%n",className,commentText);
         }
 
-        for(PackageDoc currentPackage: packages) {
+        for(PackageDoc currentPackage: packages)
-            String commentText = formatText(currentPackage.commentText());
+            renderHelpText(currentPackage.name(),currentPackage,out);
-            if(commentText.length() > 0)
-                out.printf("%s=%s%n",currentPackage.name(),commentText);
-        }
 
         return true;
     }
@@ -68,6 +63,25 @@ public class HelpExtractorDoclet {
         return 0;
     }
 
+    /**
+     * Renders all the help text required for a given name.
+     * @param elementName element name to use as the key
+     * @param element Doc element to process.
+     * @param out Output stream to which to write.
+     */
+    private static void renderHelpText(String elementName, Doc element, PrintStream out) {
+        // Provide a new display name if provided by the user.
+        Tag[] tags = element.tags("@"+DisplayNameTaglet.NAME);
+        if(tags.length > 1)
+            throw new StingException("Cannot provide multiple display names for a single tag.");
+        if(tags.length == 1)
+            out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,tags[0].text());
+
+        String commentText = formatText(element.commentText());
+        if(commentText.length() > 0)
+            out.printf("%s=%s%n",elementName,commentText);
+    }
+
     /**
      * Format text for consumption by the properties file.
      * @param text Text to format.