From 8089aa3c50b42a7ca1a97753791486c552d65b52 Mon Sep 17 00:00:00 2001 From: hanna Date: Mon, 7 Dec 2009 00:16:26 +0000 Subject: [PATCH] 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 --- .../playground/gatk/walkers/package-info.java | 2 +- .../sting/utils/doc/DescriptionTaglet.java | 120 ++++++++++++++++++ .../sting/utils/doc/DisplayNameTaglet.java | 2 +- .../sting/utils/doc/HelpExtractorDoclet.java | 29 +++-- 4 files changed, 142 insertions(+), 11 deletions(-) create mode 100644 java/src/org/broadinstitute/sting/utils/doc/DescriptionTaglet.java 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 index efc3934da..7ced4fc8e 100644 --- a/java/src/org/broadinstitute/sting/playground/gatk/walkers/package-info.java +++ b/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; \ No newline at end of file diff --git a/java/src/org/broadinstitute/sting/utils/doc/DescriptionTaglet.java b/java/src/org/broadinstitute/sting/utils/doc/DescriptionTaglet.java new file mode 100644 index 000000000..7b5a419f5 --- /dev/null +++ b/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 @WalkerName 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 @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) { + 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; + } +} \ 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 index 3c6493763..2837a2237 100644 --- a/java/src/org/broadinstitute/sting/utils/doc/DisplayNameTaglet.java +++ b/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. diff --git a/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java b/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java index 12e2aca94..2daf960e5 100644 --- a/java/src/org/broadinstitute/sting/utils/doc/HelpExtractorDoclet.java +++ b/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. - 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()); + // Extract overrides from the doc tags. + String overrideName = null; + String overrideDescription = element.commentText(); + for(Tag tag: element.tags()) { + if(tag.name().equals("@"+DisplayNameTaglet.NAME)) { + 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()); - if(commentText.length() > 0) - out.printf("%s=%s%n",elementName,commentText); + // Write out an alternate element name, if exists. + if(overrideName != null) + 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); } /**