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

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()))
+        if(analysisName != null && walkerManager.exists(getAnalysisName()))
-            additionalHelp = getWalkerHelp();
+            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<Walker> 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() {
+    private String getAllWalkerHelp() {
-        final int PACKAGE_INDENT = 1;
-        final int WALKER_INDENT = 3;
-        final String FIELD_SEPARATOR = "  ";
-
         // 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<? extends Walker> 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<HelpEntry> 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<HelpEntry> children)  {
+    public HelpEntry(String uid, String displayName, String summary, SortedSet<HelpEntry> 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) {
+    public HelpEntry(String uid, String displayName, String summary) {
-        this(uid,displayName,description,null);
+        this(uid,displayName,summary,null);
     }
 
 }

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<Walker> {
      */
     public String getPackageDisplayName(String packageName) {
         // Try to find an override for the display name of this package.
-        String displayName = helpText.getProperty(packageName+"."+ DisplayNameTaglet.NAME);
+        String displayNameKey = String.format("%s.%s",packageName,DisplayNameTaglet.NAME);
-        // If no override exists...
+        String displayName = null;
-        if(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 = "<unpackaged>";
-
         }
         return displayName;
     }
@@ -112,22 +117,35 @@ public class WalkerManager extends PluginManager<Walker> {
      * @param packageName Package for which to search for help text.
      * @return Package help text, or "" if none exists.
      */
-    public String getPackageHelpText(String packageName) {
+    public String getPackageSummaryText(String packageName) {
-        if(!helpText.containsKey(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<? extends Walker> walkerType) {
+    public String getWalkerSummaryText(Class<? extends Walker> walkerType) {
-        String walkerName = walkerType.getName();
+        String walkerSummary = String.format("%s.%s",walkerType.getName(), SummaryTaglet.NAME);
-        if(!helpText.containsKey(walkerName))
+        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<? extends Walker> 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<Walker> {
      * @param walkerName Name of the walker.
      * @return Class representing the walker.
      */
-    public Class getWalkerClassByName(String walkerName) {
+    public Class<Walker> getWalkerClassByName(String walkerName) {
-        return pluginsByName.get(walkerName);
+        return (Class<Walker>)pluginsByName.get(walkerName);
     }
 
     /**

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] <in.alignment>
+ * Prints the alignment in the pileup format. In the pileup format, each line represents a genomic position,
- *
- * Print 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,
+ * Associated command:
- * consisting of chromosome name, coordinate, reference base, read bases, read qualities and alignment mapping
+ * samtools pileup [-f in.ref.fasta] [-t in.ref_list] [-l in.site_list] [-iscg] [-T theta] [-N nHap] [-r pairDiffRate] <in.alignment>
- * 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.
  */
 public class PileupWalker extends LocusWalker<Integer, Integer> implements TreeReducible<Integer> {
     @Argument(fullName="alwaysShowSecondBase",doc="If true, prints dummy bases for the second bases in the BAM file where they are missing",required=false)

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

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")

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 outputs a text based call format. Intended to be used only as an
- * A simple Bayesian genotyper, that output a text based call format. Intended to be used only as an
  * example in the GATK publication.
- *
+ * @author aaron
- * @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
+ * @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<SimpleCall, Integer> implements TreeReducible<Integer> {
 

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 <code>@WalkerName</code> 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 <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.
@@ -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;
-    }
 }

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 <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
      */
+    @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 <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.
@@ -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;
-    }
 }

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 name = null;
-        String overrideDescription = element.firstSentenceTags().length > 0 ? element.firstSentenceTags()[0].text() : "";
+        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)
+        if(name != null)
-            out.printf("%s.%s=%s%n",elementName,DisplayNameTaglet.NAME,overrideName);
+            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);
+        out.printf("%s.%s=%s%n",elementName,DescriptionTaglet.NAME,formatText(description));
-        if(description.length() > 0)
-            out.printf("%s=%s%n",elementName,description);
     }
 
     /**

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;
+    }
+}

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 <code>@WalkerName</code> 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);
+    }
+}