Adding support to override the help text.

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

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

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

java/src/org/broadinstitute/sting/utils/doc/DescriptionTaglet.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 an alternate description for the given help system.
+ *
+ * @author mhanna
+ * @version 0.1
+ */
+public class DescriptionTaglet implements Taglet {
+    /**
+     * The key tag for this taglet.
+     */
+    public static final String NAME = "help.description";
+
+    /**
+     * 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 true;
+    }
+
+    /**
+     * Will return true to indicate that packages can be given useful
+     * description.
+     * @return true always
+     */
+    public boolean inPackage() {
+        return true;
+    }
+
+    /**
+     * Will return false indicating that types cannot be given
+     * alternate description.
+     * @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) {
+       DescriptionTaglet tag = new DescriptionTaglet();
+       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/DisplayNameTaglet.java

@@ -15,7 +15,7 @@ public class DisplayNameTaglet implements Taglet {
     /**
      * The display name for this taglet.
      */
-    public static final String NAME = "display.name";
+    public static final String NAME = "help.display.name";
 
     /**
      * Return the name of this custom tag.

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

@@ -70,16 +70,27 @@ public class HelpExtractorDoclet {
      * @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.
+        // Extract overrides from the doc tags.
-        Tag[] tags = element.tags("@"+DisplayNameTaglet.NAME);
+        String overrideName = null;
-        if(tags.length > 1)
+        String overrideDescription = element.commentText();
-            throw new StingException("Cannot provide multiple display names for a single tag.");
+        for(Tag tag: element.tags()) {
-        if(tags.length == 1)
+            if(tag.name().equals("@"+DisplayNameTaglet.NAME)) {
-            out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,tags[0].text());
+                if(overrideName != null)
+                    throw new StingException("Only one display name tag can be used per package / walker.");
+                overrideName = tag.text();
+            }
+            else if(tag.name().equals("@"+DescriptionTaglet.NAME))
+                overrideDescription = tag.text();
+        }
 
-        String commentText = formatText(element.commentText());
+        // Write out an alternate element name, if exists.
-        if(commentText.length() > 0)
+        if(overrideName != null)
-            out.printf("%s=%s%n",elementName,commentText);
+            out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,overrideName);
+
+        // Write out an alternate description, if present.
+        String description = formatText(overrideDescription);
+        if(description.length() > 0)
+            out.printf("%s=%s%n",elementName,description);
     }
 
     /**