From 3b440e0dbcd6fbc587330e4320bf032442eee6b0 Mon Sep 17 00:00:00 2001 From: hanna Date: Sun, 6 Dec 2009 04:12:10 +0000 Subject: [PATCH] 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 --- .../sting/gatk/WalkerManager.java | 4 +- .../playground/gatk/walkers/package-info.java | 4 + .../sting/utils/doc/DisplayNameTaglet.java | 120 ++++++++++++++++++ .../sting/utils/doc/HelpExtractorDoclet.java | 36 ++++-- 4 files changed, 152 insertions(+), 12 deletions(-) create mode 100644 java/src/org/broadinstitute/sting/playground/gatk/walkers/package-info.java create mode 100644 java/src/org/broadinstitute/sting/utils/doc/DisplayNameTaglet.java diff --git a/java/src/org/broadinstitute/sting/gatk/WalkerManager.java b/java/src/org/broadinstitute/sting/gatk/WalkerManager.java index a5e134d05..6d633035f 100755 --- a/java/src/org/broadinstitute/sting/gatk/WalkerManager.java +++ b/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 { * @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); } /** diff --git a/java/src/org/broadinstitute/sting/playground/gatk/walkers/package-info.java b/java/src/org/broadinstitute/sting/playground/gatk/walkers/package-info.java new file mode 100644 index 000000000..efc3934da --- /dev/null +++ b/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; \ No newline at end of file diff --git a/java/src/org/broadinstitute/sting/utils/doc/DisplayNameTaglet.java b/java/src/org/broadinstitute/sting/utils/doc/DisplayNameTaglet.java new file mode 100644 index 000000000..3c6493763 --- /dev/null +++ b/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 @WalkerName 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 @todo + * is not an inline tag. + * @return false since @todo + * 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; + } +} diff --git a/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java b/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java index 0db041617..12e2aca94 100644 --- a/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java +++ b/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.PackageDoc; -import com.sun.javadoc.ClassDoc; +import com.sun.javadoc.*; 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) - out.printf("%s=%s%n",className,commentText); + renderHelpText(className,currentClass,out); } - for(PackageDoc currentPackage: packages) { - String commentText = formatText(currentPackage.commentText()); - if(commentText.length() > 0) - out.printf("%s=%s%n",currentPackage.name(),commentText); - } + for(PackageDoc currentPackage: packages) + renderHelpText(currentPackage.name(),currentPackage,out); 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.