From 6955b5bf537ab1338faf83904de50a6c26e5e033 Mon Sep 17 00:00:00 2001 From: hanna Date: Sat, 12 Dec 2009 04:04:37 +0000 Subject: [PATCH] Cleanup of the doc system, and introduce Kiran's concept of a detailed summary below the specific command-line arguments for the walker. Also introduced @help.summary to override summary descriptions if required. git-svn-id: file:///humgen/gsa-scr1/gsa-engineering/svn_contents/trunk@2337 348d0f76-0448-11de-a6fe-93d51630548a --- .../sting/gatk/CommandLineGATK.java | 60 +++++++----- .../sting/gatk/WalkerManager.java | 48 +++++++--- .../sting/gatk/walkers/PileupWalker.java | 12 +-- .../recalibration/CovariateCounterWalker.java | 8 +- .../TableRecalibrationWalker.java | 8 +- .../papergenotyper/GATKPaperGenotyper.java | 7 +- .../sting/utils/help/DescriptionTaglet.java | 68 +------------- .../sting/utils/help/DisplayNameTaglet.java | 76 +-------------- .../sting/utils/help/HelpExtractorDoclet.java | 28 ++++-- .../sting/utils/help/HelpTaglet.java | 93 +++++++++++++++++++ .../sting/utils/help/SummaryTaglet.java | 59 ++++++++++++ 11 files changed, 261 insertions(+), 206 deletions(-) create mode 100644 java/src/org/broadinstitute/sting/utils/help/HelpTaglet.java create mode 100644 java/src/org/broadinstitute/sting/utils/help/SummaryTaglet.java diff --git a/java/src/org/broadinstitute/sting/gatk/CommandLineGATK.java b/java/src/org/broadinstitute/sting/gatk/CommandLineGATK.java index f7ffbe41f..79f114955 100755 --- a/java/src/org/broadinstitute/sting/gatk/CommandLineGATK.java +++ b/java/src/org/broadinstitute/sting/gatk/CommandLineGATK.java @@ -117,22 +117,40 @@ public class CommandLineGATK extends CommandLineExecutable { String additionalHelp = ""; // If no analysis name is present, fill in extra help on the walkers. + WalkerManager walkerManager = GATKEngine.getWalkerManager(); String analysisName = getAnalysisName(); - if(analysisName == null || !GATKEngine.getWalkerManager().exists(getAnalysisName())) - additionalHelp = getWalkerHelp(); + if(analysisName != null && walkerManager.exists(getAnalysisName())) + additionalHelp = getWalkerHelp(walkerManager.getWalkerClassByName(getAnalysisName())); + else + additionalHelp = getAllWalkerHelp(); return additionalHelp; } + private static final int PACKAGE_INDENT = 1; + private static final int WALKER_INDENT = 3; + private static final String FIELD_SEPARATOR = " "; + + private String getWalkerHelp(Class walkerType) { + // Construct a help string to output details on this walker. + StringBuilder additionalHelp = new StringBuilder(); + Formatter formatter = new Formatter(additionalHelp); + + formatter.format("Description:%n"); + + WalkerManager walkerManager = GATKEngine.getWalkerManager(); + String walkerHelpText = walkerManager.getWalkerDescriptionText(walkerType); + + printDescriptorLine(formatter,WALKER_INDENT,"",WALKER_INDENT,FIELD_SEPARATOR,walkerHelpText,TextFormattingUtils.DEFAULT_LINE_WIDTH); + + return additionalHelp.toString(); + } + /** * Load in additional help information about all available walkers. * @return A string representation of the additional help. */ - private String getWalkerHelp() { - final int PACKAGE_INDENT = 1; - final int WALKER_INDENT = 3; - final String FIELD_SEPARATOR = " "; - + private String getAllWalkerHelp() { // Construct a help string to output available walkers. StringBuilder additionalHelp = new StringBuilder(); Formatter formatter = new Formatter(additionalHelp); @@ -152,7 +170,7 @@ public class CommandLineGATK extends CommandLineExecutable { // Get the display name. String packageName = walkersByPackage.getKey(); String packageDisplayName = walkerManager.getPackageDisplayName(walkersByPackage.getKey()); - String packageHelpText = walkerManager.getPackageHelpText(packageName); + String packageHelpText = walkerManager.getPackageSummaryText(packageName); // Compute statistics about which names is longest. longestPackageName = Math.max(longestPackageName,packageDisplayName.length()); @@ -161,7 +179,7 @@ public class CommandLineGATK extends CommandLineExecutable { for(Class walkerType: walkersByPackage.getValue()) { String walkerName = walkerType.getName(); String walkerDisplayName = walkerManager.getName(walkerType); - String walkerHelpText = walkerManager.getWalkerHelpText(walkerType); + String walkerHelpText = walkerManager.getWalkerSummaryText(walkerType); longestWalkerName = Math.max(longestWalkerName,walkerManager.getName(walkerType).length()); @@ -176,10 +194,10 @@ public class CommandLineGATK extends CommandLineExecutable { for(HelpEntry packageHelp: helpText) { - printDescriptorLine(formatter,PACKAGE_INDENT,packageHelp.displayName,headerWidth,FIELD_SEPARATOR,packageHelp.description,TextFormattingUtils.DEFAULT_LINE_WIDTH); + printDescriptorLine(formatter,PACKAGE_INDENT,packageHelp.displayName,headerWidth,FIELD_SEPARATOR,packageHelp.summary,TextFormattingUtils.DEFAULT_LINE_WIDTH); for(HelpEntry walkerHelp: packageHelp.children) - printDescriptorLine(formatter,WALKER_INDENT,walkerHelp.displayName,headerWidth,FIELD_SEPARATOR,walkerHelp.description,TextFormattingUtils.DEFAULT_LINE_WIDTH); + printDescriptorLine(formatter,WALKER_INDENT,walkerHelp.displayName,headerWidth,FIELD_SEPARATOR,walkerHelp.summary,TextFormattingUtils.DEFAULT_LINE_WIDTH); // Print a blank line between sets of walkers. printDescriptorLine(formatter,0,"",headerWidth,FIELD_SEPARATOR,"", TextFormattingUtils.DEFAULT_LINE_WIDTH); @@ -213,36 +231,36 @@ public class CommandLineGATK extends CommandLineExecutable { } /** - * Represents a given help entry; contains a display name, a description and optionally some children. + * Represents a given help entry; contains a display name, a summary and optionally some children. */ class HelpEntry { public final String uid; public final String displayName; - public final String description; + public final String summary; public final SortedSet children; /** - * Create a new help entry with the given display name, description and children. + * Create a new help entry with the given display name, summary and children. * @param uid a unique identifier. Usually, the java package. * @param displayName display name for this help entry. - * @param description description for this help entry. + * @param summary summary for this help entry. * @param children children for this help entry. */ - public HelpEntry(String uid, String displayName, String description, SortedSet children) { + public HelpEntry(String uid, String displayName, String summary, SortedSet children) { this.uid = uid; this.displayName = displayName; - this.description = description; + this.summary = summary; this.children = children; } /** - * Create a new help entry with the given display name, description and children. + * Create a new help entry with the given display name, summary and children. * @param uid a unique identifier. Usually, the java package. * @param displayName display name for this help entry. - * @param description description for this help entry. + * @param summary summary for this help entry. */ - public HelpEntry(String uid, String displayName, String description) { - this(uid,displayName,description,null); + public HelpEntry(String uid, String displayName, String summary) { + this(uid,displayName,summary,null); } } diff --git a/java/src/org/broadinstitute/sting/gatk/WalkerManager.java b/java/src/org/broadinstitute/sting/gatk/WalkerManager.java index 93f4585c9..bd6dc5e9d 100755 --- a/java/src/org/broadinstitute/sting/gatk/WalkerManager.java +++ b/java/src/org/broadinstitute/sting/gatk/WalkerManager.java @@ -36,6 +36,8 @@ import org.broadinstitute.sting.gatk.filters.FilterManager; import org.broadinstitute.sting.utils.StingException; import org.broadinstitute.sting.utils.PluginManager; import org.broadinstitute.sting.utils.help.DisplayNameTaglet; +import org.broadinstitute.sting.utils.help.DescriptionTaglet; +import org.broadinstitute.sting.utils.help.SummaryTaglet; import org.apache.log4j.Logger; import net.sf.picard.filter.SamRecordFilter; @@ -95,14 +97,17 @@ public class WalkerManager extends PluginManager { */ public String getPackageDisplayName(String packageName) { // Try to find an override for the display name of this package. - String displayName = helpText.getProperty(packageName+"."+ DisplayNameTaglet.NAME); - // If no override exists... - if(displayName == null) { + String displayNameKey = String.format("%s.%s",packageName,DisplayNameTaglet.NAME); + String displayName = null; + if(helpText.containsKey(displayNameKey)) { + displayName = helpText.getProperty(displayNameKey); + } + else { + // If no override exists... // ...try to compute the override from the text of the package name, while accounting for // unpackaged walkers. displayName = packageName.substring(packageName.lastIndexOf('.')+1); if(displayName.trim().equals("")) displayName = ""; - } return displayName; } @@ -112,22 +117,35 @@ public class WalkerManager extends PluginManager { * @param packageName Package for which to search for help text. * @return Package help text, or "" if none exists. */ - public String getPackageHelpText(String packageName) { - if(!helpText.containsKey(packageName)) + public String getPackageSummaryText(String packageName) { + String key = String.format("%s.%s",packageName,SummaryTaglet.NAME); + if(!helpText.containsKey(key)) return ""; - return helpText.getProperty(packageName); + return helpText.getProperty(key); } /** - * Gets the help text associated with a given walker type. + * Gets the summary help text associated with a given walker type. * @param walkerType Type of walker for which to search for help text. - * @return Package help text, or "" if none exists. + * @return Walker summary description, or "" if none exists. */ - public String getWalkerHelpText(Class walkerType) { - String walkerName = walkerType.getName(); - if(!helpText.containsKey(walkerName)) + public String getWalkerSummaryText(Class walkerType) { + String walkerSummary = String.format("%s.%s",walkerType.getName(), SummaryTaglet.NAME); + if(!helpText.containsKey(walkerSummary)) return ""; - return helpText.getProperty(walkerName); + return helpText.getProperty(walkerSummary); + } + + /** + * Gets the descriptive help text associated with a given walker type. + * @param walkerType Type of walker for which to search for help text. + * @return Walker full description, or "" if none exists. + */ + public String getWalkerDescriptionText(Class walkerType) { + String walkerDescription = String.format("%s.%s",walkerType.getName(), DescriptionTaglet.NAME); + if(!helpText.containsKey(walkerDescription)) + return ""; + return helpText.getProperty(walkerDescription); } /** @@ -135,8 +153,8 @@ public class WalkerManager extends PluginManager { * @param walkerName Name of the walker. * @return Class representing the walker. */ - public Class getWalkerClassByName(String walkerName) { - return pluginsByName.get(walkerName); + public Class getWalkerClassByName(String walkerName) { + return (Class)pluginsByName.get(walkerName); } /** diff --git a/java/src/org/broadinstitute/sting/gatk/walkers/PileupWalker.java b/java/src/org/broadinstitute/sting/gatk/walkers/PileupWalker.java index 29b845d83..bcdc3db42 100644 --- a/java/src/org/broadinstitute/sting/gatk/walkers/PileupWalker.java +++ b/java/src/org/broadinstitute/sting/gatk/walkers/PileupWalker.java @@ -36,9 +36,7 @@ import org.broadinstitute.sting.utils.Utils; import java.util.ArrayList; /** - * samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list] [-iscg] [-T theta] [-N nHap] [-r pairDiffRate] - * - * Print the alignment in the pileup format. In the pileup format, each line represents a genomic position, + * Prints the alignment in the pileup format. In the pileup format, each line represents a genomic position, * consisting of chromosome name, coordinate, reference base, read bases, read qualities and alignment mapping * qualities. Information on match, mismatch, indel, strand, mapping quality and start and end of a read are all * encoded at the read base column. At this column, a dot stands for a match to the reference base on the forward strand, @@ -52,12 +50,8 @@ import java.util.ArrayList; * separated by 'N/S/H' CIGAR operations. The ASCII of the character following '^' minus 33 gives the mapping quality. * A symbol '$' marks the end of a read segment. * - * @help.description Prints the alignment in the pileup format. In the pileup format, each line represents a genomic position, - * consisting of chromosome name, coordinate, reference base, read bases, read qualities and alignment mapping - * qualities. Information on match, mismatch, indel, strand, mapping quality and start and end of a read are all - * encoded at the read base column. At this column, a dot stands for a match to the reference base on the forward strand, - * a comma for a match on the reverse strand, 'ACGTN' for a mismatch on the forward strand and 'acgtn' for a mismatch on the - * reverse strand. + * Associated command: + * samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list] [-iscg] [-T theta] [-N nHap] [-r pairDiffRate] */ public class PileupWalker extends LocusWalker implements TreeReducible { @Argument(fullName="alwaysShowSecondBase",doc="If true, prints dummy bases for the second bases in the BAM file where they are missing",required=false) diff --git a/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/CovariateCounterWalker.java b/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/CovariateCounterWalker.java index 83a997f57..87ac86afc 100755 --- a/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/CovariateCounterWalker.java +++ b/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/CovariateCounterWalker.java @@ -46,10 +46,6 @@ import net.sf.samtools.SAMRecord; */ /** - * Created by IntelliJ IDEA. - * User: rpoplin - * Date: Nov 3, 2009 - * * This walker is designed to work as the first pass in a two-pass processing step. * It does a by-locus traversal operating only at sites that are not in dbSNP. * We assume that all reference mismatches we see are therefore errors and indicitive of poor base quality. @@ -62,7 +58,9 @@ import net.sf.samtools.SAMRecord; * Note: ReadGroupCovariate and QualityScoreCovariate are required covariates and must be at the start of the list. * Note: This walker is designed to be used in conjunction with TableRecalibrationWalker. * - * @help.description First pass of the recalibration. Generates recalibration table based on various user-specified covariates (such as reported quality score, cycle, and dinucleotide). + * @author rpoplin + * @since Nov 3, 2009 + * @help.summary First pass of the recalibration. Generates recalibration table based on various user-specified covariates (such as reported quality score, cycle, and dinucleotide). */ @By( DataSource.READS ) // Only look at covered loci, not every loci of the reference file diff --git a/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/TableRecalibrationWalker.java b/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/TableRecalibrationWalker.java index 6ae72dbd5..7e09f9d18 100644 --- a/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/TableRecalibrationWalker.java +++ b/java/src/org/broadinstitute/sting/gatk/walkers/recalibration/TableRecalibrationWalker.java @@ -43,10 +43,6 @@ import java.io.FileNotFoundException; */ /** - * Created by IntelliJ IDEA. - * User: rpoplin - * Date: Nov 3, 2009 - * * This walker is designed to work as the second pass in a two-pass processing step, doing a by-read traversal. * For each base in each read this walker calculates various user-specified covariates (such as read group, reported quality score, cycle, and dinuc) @@ -56,7 +52,9 @@ import java.io.FileNotFoundException; * Note: This walker expects as input the recalibration table file generated previously by CovariateCounterWalker. * Note: This walker is designed to be used in conjunction with CovariateCounterWalker. * - * @help.description Second pass of the recalibration. Uses the table generated by CountCovariates to update the base quality scores of the input bam file using a sequential table calculation making the base quality scores more accurately reflect the actual quality of the bases as mesaured by reference mismatch rate. + * @author rpoplin + * @since Nov 3, 2009 + * @help.summary Second pass of the recalibration. Uses the table generated by CountCovariates to update the base quality scores of the input bam file using a sequential table calculation making the base quality scores more accurately reflect the actual quality of the bases as mesaured by reference mismatch rate. */ @WalkerName("TableRecalibration") diff --git a/java/src/org/broadinstitute/sting/playground/gatk/walkers/papergenotyper/GATKPaperGenotyper.java b/java/src/org/broadinstitute/sting/playground/gatk/walkers/papergenotyper/GATKPaperGenotyper.java index a369086c3..3a00c282b 100644 --- a/java/src/org/broadinstitute/sting/playground/gatk/walkers/papergenotyper/GATKPaperGenotyper.java +++ b/java/src/org/broadinstitute/sting/playground/gatk/walkers/papergenotyper/GATKPaperGenotyper.java @@ -14,11 +14,10 @@ import java.io.PrintStream; /** - * @author aaron - * A simple Bayesian genotyper, that output a text based call format. Intended to be used only as an + * A simple Bayesian genotyper, that outputs a text based call format. Intended to be used only as an * example in the GATK publication. - * - * @help.description A simple, naive Bayesian genotyper that is used as an example locus walker in the GATK paper. THIS IS NOT TO BE USED FOR ANY ANALYSIS + * @author aaron + * @help.summary A simple, naive Bayesian genotyper that is used as an example locus walker in the GATK paper. THIS IS NOT TO BE USED FOR ANY ANALYSIS */ public class GATKPaperGenotyper extends LocusWalker implements TreeReducible { diff --git a/java/src/org/broadinstitute/sting/utils/help/DescriptionTaglet.java b/java/src/org/broadinstitute/sting/utils/help/DescriptionTaglet.java index 4f0459a08..68633a2b3 100644 --- a/java/src/org/broadinstitute/sting/utils/help/DescriptionTaglet.java +++ b/java/src/org/broadinstitute/sting/utils/help/DescriptionTaglet.java @@ -11,7 +11,7 @@ import java.util.Map; * @author mhanna * @version 0.1 */ -public class DescriptionTaglet implements Taglet { +public class DescriptionTaglet extends HelpTaglet { /** * The key tag for this taglet. */ @@ -20,42 +20,17 @@ public class DescriptionTaglet implements Taglet { /** * Return the name of this custom tag. */ + @Override 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 */ + @Override public boolean inOverview() { return true; } @@ -65,30 +40,11 @@ public class DescriptionTaglet implements Taglet { * description. * @return true always */ + @Override 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. @@ -101,20 +57,4 @@ public class DescriptionTaglet implements Taglet { } 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/help/DisplayNameTaglet.java b/java/src/org/broadinstitute/sting/utils/help/DisplayNameTaglet.java index d2bf948dc..be6f7f3eb 100644 --- a/java/src/org/broadinstitute/sting/utils/help/DisplayNameTaglet.java +++ b/java/src/org/broadinstitute/sting/utils/help/DisplayNameTaglet.java @@ -11,7 +11,7 @@ import java.util.Map; * @author mhanna * @version 0.1 */ -public class DisplayNameTaglet implements Taglet { +public class DisplayNameTaglet extends HelpTaglet { /** * The display name for this taglet. */ @@ -20,75 +20,21 @@ public class DisplayNameTaglet implements Taglet { /** * Return the name of this custom tag. */ + @Override 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 */ + @Override 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. @@ -101,20 +47,4 @@ public class DisplayNameTaglet implements Taglet { } 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/help/HelpExtractorDoclet.java b/java/src/org/broadinstitute/sting/utils/help/HelpExtractorDoclet.java index 8d8db5fa7..a5edb412d 100644 --- a/java/src/org/broadinstitute/sting/utils/help/HelpExtractorDoclet.java +++ b/java/src/org/broadinstitute/sting/utils/help/HelpExtractorDoclet.java @@ -71,26 +71,34 @@ public class HelpExtractorDoclet { */ private static void renderHelpText(String elementName, Doc element, PrintStream out) { // Extract overrides from the doc tags. - String overrideName = null; - String overrideDescription = element.firstSentenceTags().length > 0 ? element.firstSentenceTags()[0].text() : ""; + String name = null; + StringBuilder summaryBuilder = new StringBuilder(); + for(Tag tag: element.firstSentenceTags()) + summaryBuilder.append(tag.text()); + String summary = summaryBuilder.toString(); + String description = element.commentText(); + for(Tag tag: element.tags()) { if(tag.name().equals("@"+DisplayNameTaglet.NAME)) { - if(overrideName != null) + if(name != null) throw new StingException("Only one display name tag can be used per package / walker."); - overrideName = tag.text(); + name = tag.text(); } + else if(tag.name().equals("@"+SummaryTaglet.NAME)) + summary = tag.text(); else if(tag.name().equals("@"+DescriptionTaglet.NAME)) - overrideDescription = tag.text(); + description = tag.text(); } // Write out an alternate element name, if exists. - if(overrideName != null) - out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,overrideName); + if(name != null) + out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,name); + + // Write out an alternate element summary, if exists. + out.printf("%s.%s=%s%n",elementName,SummaryTaglet.NAME,formatText(summary)); // Write out an alternate description, if present. - String description = formatText(overrideDescription); - if(description.length() > 0) - out.printf("%s=%s%n",elementName,description); + out.printf("%s.%s=%s%n",elementName,DescriptionTaglet.NAME,formatText(description)); } /** diff --git a/java/src/org/broadinstitute/sting/utils/help/HelpTaglet.java b/java/src/org/broadinstitute/sting/utils/help/HelpTaglet.java new file mode 100644 index 000000000..b962664eb --- /dev/null +++ b/java/src/org/broadinstitute/sting/utils/help/HelpTaglet.java @@ -0,0 +1,93 @@ +package org.broadinstitute.sting.utils.help; + +import com.sun.tools.doclets.Taglet; +import com.sun.javadoc.Tag; + +import java.util.Map; + +/** + * Basic functionality for the help taglet. + * + * @author mhanna + * @version 0.1 + */ +public abstract class HelpTaglet implements Taglet { + /** + * Return the name of this custom tag. + */ + public abstract String getName(); + + /** + * 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 by default, help tags cannot be applied to a constructor. + * @return false since by default, help tags cannot be applied to a constructor. + */ + public boolean inConstructor() { + return false; + } + + /** + * Will return false since by default, help tags cannot be applied to a method. + * @return false since by default, this tag cannot be applied to a method. + */ + public boolean inMethod() { + return false; + } + + /** + * Will return false since by default, help tags cannot be applied to an overview. + * @return false since by default, help tags cannot be applied to an overview. + */ + public boolean inOverview() { + return false; + } + + /** + * Will return false since by default, help tags cannot be applied to a package. + * description. + * @return false since by default, help tags cannot be applied to a package. + */ + public boolean inPackage() { + return false; + } + + /** + * Will return false since help tags are by default not inline. + * @return false since help tags are by default not inline. + */ + public boolean inType() { + return false; + } + + /** + * Will return false since help tags are by default not inline. + * @return false since help tags are by default not inline. + */ + public boolean isInlineTag() { + return false; + } + + /** + * 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/help/SummaryTaglet.java b/java/src/org/broadinstitute/sting/utils/help/SummaryTaglet.java new file mode 100644 index 000000000..036bbec4f --- /dev/null +++ b/java/src/org/broadinstitute/sting/utils/help/SummaryTaglet.java @@ -0,0 +1,59 @@ +package org.broadinstitute.sting.utils.help; + +import com.sun.tools.doclets.Taglet; +import com.sun.javadoc.Tag; + +import java.util.Map; + +/** + * Provide an alternate brief summary for this walker / package. + * Acts as an alternative to the first sentence employed by default. + * @author mhanna + * @version 0.1 + */ +public class SummaryTaglet extends HelpTaglet { + /** + * The key tag for this taglet. + */ + public static final String NAME = "help.summary"; + + /** + * Return the name of this custom tag. + */ + @Override + public String getName() { + return NAME; + } + + /** + * Will return false since overviews are always named + * by the @WalkerName tag. + * @return false always + */ + @Override + public boolean inOverview() { + return true; + } + + /** + * Will return true to indicate that packages can be given useful summary. + * @return true always + */ + @Override + public boolean inPackage() { + return true; + } + + /** + * Register this Taglet. + * @param tagletMap the map to register this tag to. + */ + public static void register(Map tagletMap) { + SummaryTaglet tag = new SummaryTaglet(); + Taglet t = (Taglet)tagletMap.get(tag.getName()); + if (t != null) { + tagletMap.remove(tag.getName()); + } + tagletMap.put(tag.getName(), tag); + } +} \ No newline at end of file