+ * The format includes eleven standard fields, plus genotypes for each of the samples included
+ * in the file:
+ *
+ *
{
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/sampileup/SAMPileupCodec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/sampileup/SAMPileupCodec.java
index f4048d37d..f4633b2ce 100644
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/sampileup/SAMPileupCodec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/sampileup/SAMPileupCodec.java
@@ -38,10 +38,43 @@ import java.util.regex.Pattern;
import static org.broadinstitute.sting.utils.codecs.sampileup.SAMPileupFeature.VariantType;
/**
- * A Tribble encoder / decoder for SAM pileup data.
+ * Decoder for SAM pileup data. For GATK validation purposes only
*
- * @author mhanna
- * @version 0.1
+ *
+ * Pileup format is first used by Tony Cox and Zemin Ning at the Sanger Institute.
+ * It desribes the base-pair information at each chromosomal position. This format
+ * facilitates SNP/indel calling and brief alignment viewing by eyes.
+ *
+ *
+ * Each line consists of chromosome, 1-based coordinate, reference base, the
+ * number of reads covering the site, read bases and base qualities. At the
+ * read base 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.
+ * A pattern `\+[0-9]+[ACGTNacgtn]+' indicates there is an insertion between
+ * this reference position and the next reference position. The length of the
+ * insertion is given by the integer in the pattern, followed by the inserted sequence.
+ *
+ *
+ *
+ *
See also: @see SAMTools project
+ *
See also: @see Pileup format
+ *
+ *
+ * File format example
+ *
+ * seq1 272 T 24 ,.$.....,,.,.,...,,,.,..^+. <<<+;<<<<<<<<<<<=<;<;7<&
+ * seq1 273 T 23 ,.....,,.,.,...,,,.,..A <<<;<<<<<<<<<3<=<<<;<<+
+ * seq1 274 T 23 ,.$....,,.,.,...,,,.,... 7<7;<;<<<<<<<<<=<;<;<<6
+ * seq1 275 A 23 ,$....,,.,.,...,,,.,...^l. <+;9*<<<<<<<<<=<<:;<<<<
+ * seq1 276 G 22 ...T,,.,.,...,,,.,.... 33;+<<7=7<<7<&<<1;<<6<
+ * seq1 277 T 22 ....,,.,.,.C.,,,.,..G. +7<;<<<<<<<&<=<<:;<<&<
+ * seq1 278 G 23 ....,,.,.,...,,,.,....^k. %38*<<;<7<<7<=<<<;<<<<<
+ * seq1 279 C 23 A..T,,.,.,...,,,.,..... ;75&<<<<<<<<<=<<<9<<:<<
+ *
+ *
+ * @author Matt Hanna
+ * @since 2009
*/
public class SAMPileupCodec implements FeatureCodec {
// the number of tokens we expect to parse from a pileup line
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/samread/SAMReadCodec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/samread/SAMReadCodec.java
index f6861e585..d4bdb5aa9 100644
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/samread/SAMReadCodec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/samread/SAMReadCodec.java
@@ -36,8 +36,21 @@ import org.broad.tribble.util.ParsingUtils;
/**
* Decodes a simple SAM text string.
*
- * @author mhanna
- * @version 0.1
+ *
+ * Reads in the SAM text version of a BAM file as a ROD. For testing only
+ *
+ *
+ *
+ * See also: @see SAMTools for format specification
+ *
+ *
+ * File format example
+ *
+ * SL-XBC:1:10:628:923#0 16 Escherichia_coli_K12 1 37 76M = 1 0 AGCTTTTCATTCTGACTGCAACGGGCAATATGTCTCTGTGTGGATTAAAAAAAGAGTGTCTGATAGCAGCTTCTGA B@>87<;A@?@957:>>@AA@B>@A9AB@B>@A@@@@@A;=AAB@BBBBBCBBBB@>A>:ABB@BAABCB=CA@CB
+ *
+ *
+ * @author Matt Hanna
+ * @since 2009
*/
public class SAMReadCodec implements FeatureCodec {
/* SL-XBC:1:10:628:923#0 16 Escherichia_coli_K12 1 37 76M = 1 0 AGCTTTTCATTCTGACTGCAACGGGCAATATGTCTCTGTGTGGATTAAAAAAAGAGTGTCTGATAGCAGCTTCTGA B@>87<;A@?@957:>>@AA@B>@A9AB@B>@A@@@@@A;=AAB@BBBBBCBBBB@>A>:ABB@BAABCB=CA@CB */
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/snpEff/SnpEffCodec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/snpEff/SnpEffCodec.java
index b5efb49a7..7f3d9e17d 100644
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/snpEff/SnpEffCodec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/snpEff/SnpEffCodec.java
@@ -41,10 +41,11 @@ import java.io.IOException;
/**
* Codec for decoding the output format of the SnpEff variant effect predictor tool
- * (http://snpeff.sourceforge.net/).
*
+ *
* This format has 23 tab-delimited fields:
*
+ *
* Chromosome
* Position
* Reference
@@ -68,10 +69,16 @@ import java.io.IOException;
* Codons Around
* Amino Acids Around
* Custom Interval ID
+ *
+ * Note that we treat all except the Chromosome, Position, and Effect fields as optional.
+ *
*
- * We treat all except the Chromosome, Position, and Effect fields as optional.
+ *
+ * See also: @see SNPEff project page
+ *
*
* @author David Roazen
+ * @since 2011
*/
public class SnpEffCodec implements FeatureCodec, SelfScopingFeatureCodec {
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/table/BedTableCodec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/table/BedTableCodec.java
index 6fe1907e3..fdcc8ed10 100755
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/table/BedTableCodec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/table/BedTableCodec.java
@@ -6,14 +6,19 @@ import org.broadinstitute.sting.gatk.refdata.ReferenceDependentFeatureCodec;
import java.util.Arrays;
/**
- * Created by IntelliJ IDEA.
- * User: chartl
- * Date: 3/28/11
- * Time: 2:47 PM
- * To change this template use File | Settings | File Templates.
- */
-/**
- * The standard table codec with a slightly different parsing convention (expects loci as contig start stop, not contig:start-stop)
+ * The standard table codec that expects loci as contig start stop, not contig:start-stop
+ *
+ *
+ * The standard table codec with a slightly different parsing convention
+ * (expects loci as contig start stop, not contig:start-stop)
+ *
+ *
+ *
+ * See also: TableCodec
+ *
+ *
+ * @author Chris Hartl
+ * @since 2010
*/
public class BedTableCodec extends TableCodec implements ReferenceDependentFeatureCodec {
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/table/TableCodec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/table/TableCodec.java
index 2ce7c679e..1919ccbf0 100755
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/table/TableCodec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/table/TableCodec.java
@@ -11,13 +11,40 @@ import java.util.ArrayList;
import java.util.Arrays;
/**
- * implementation of a simple table (tab or comma delimited format) input files
+ * Reads tab deliminated tabular text files
+ *
+ *
+ *
+ * - Header: must begin with line HEADER or track (for IGV), followed by any number of column names,
+ * separated by whitespace.
+ * - Comment lines starting with # are ignored
+ * - Each non-header and non-comment line is split into parts by whitespace,
+ * and these parts are assigned as a map to their corresponding column name in the header.
+ * Note that the first element (corresponding to the HEADER column) must be a valid genome loc
+ * such as 1, 1:1 or 1:1-10, which is the position of the Table element on the genome. TableCodec
+ * requires that there be one value for each column in the header, and no more, on all lines.
+ *
+ *
+ *
+ *
+ *
+ * File format example
+ *
+ * HEADER a b c
+ * 1:1 1 2 3
+ * 1:2 4 5 6
+ * 1:3 7 8 9
+ *
+ *
+ * @author Mark DePristo
+ * @since 2009
*/
public class TableCodec implements ReferenceDependentFeatureCodec {
- protected String delimiterRegex = "\\s+";
- protected String headerDelimiter = "HEADER";
- protected String igvHeaderDelimiter = "track";
- protected String commentDelimiter = "#";
+ final static protected String delimiterRegex = "\\s+";
+ final static protected String headerDelimiter = "HEADER";
+ final static protected String igvHeaderDelimiter = "track";
+ final static protected String commentDelimiter = "#";
+
protected ArrayList header = new ArrayList();
/**
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/AbstractVCFCodec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/AbstractVCFCodec.java
index 19f58ddaa..46242c302 100755
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/AbstractVCFCodec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/AbstractVCFCodec.java
@@ -14,10 +14,9 @@ import org.broadinstitute.sting.utils.variantcontext.Allele;
import org.broadinstitute.sting.utils.variantcontext.Genotype;
import org.broadinstitute.sting.utils.variantcontext.VariantContext;
-import java.io.File;
-import java.io.FileReader;
-import java.io.IOException;
+import java.io.*;
import java.util.*;
+import java.util.zip.GZIPInputStream;
public abstract class AbstractVCFCodec implements FeatureCodec, NameAwareCodec, VCFParser, SelfScopingFeatureCodec {
@@ -623,9 +622,21 @@ public abstract class AbstractVCFCodec implements FeatureCodec, NameAwareCodec,
public final static boolean canDecodeFile(final File potentialInput, final String MAGIC_HEADER_LINE) {
try {
- char[] buff = new char[MAGIC_HEADER_LINE.length()];
- new FileReader(potentialInput).read(buff, 0, MAGIC_HEADER_LINE.length());
+ return isVCFStream(new FileInputStream(potentialInput), MAGIC_HEADER_LINE) ||
+ isVCFStream(new GZIPInputStream(new FileInputStream(potentialInput)), MAGIC_HEADER_LINE);
+ } catch ( FileNotFoundException e ) {
+ return false;
+ } catch ( IOException e ) {
+ return false;
+ }
+ }
+
+ private final static boolean isVCFStream(final InputStream stream, final String MAGIC_HEADER_LINE) {
+ try {
+ byte[] buff = new byte[MAGIC_HEADER_LINE.length()];
+ stream.read(buff, 0, MAGIC_HEADER_LINE.length());
String firstLine = new String(buff);
+ stream.close();
return firstLine.startsWith(MAGIC_HEADER_LINE);
} catch ( IOException e ) {
return false;
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCF3Codec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCF3Codec.java
index ea16595bb..e5b1a2de5 100755
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCF3Codec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCF3Codec.java
@@ -14,8 +14,20 @@ import java.util.*;
/**
- * a feature codec for the VCF 3 specification. Our aim is to read in the records and convert to VariantContext as
- * quickly as possible, relying on VariantContext to do the validation of any contradictory (or malformed) record parameters.
+ * A feature codec for the VCF3 specification, to read older VCF files. VCF3 has been
+ * depreciated in favor of VCF4 (See VCF codec for the latest information)
+ *
+ *
+ * Reads historical VCF3 encoded files (1000 Genomes Pilot results, for example)
+ *
+ *
+ *
+ * See also: @see VCF specification
+ * See also: @see VCF spec. publication
+ *
+ *
+ * @author Mark DePristo
+ * @since 2010
*/
public class VCF3Codec extends AbstractVCFCodec {
public final static String VCF3_MAGIC_HEADER = "##fileformat=VCFv3";
diff --git a/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCFCodec.java b/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCFCodec.java
index 55a0eb3f9..fa030ef5f 100755
--- a/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCFCodec.java
+++ b/public/java/src/org/broadinstitute/sting/utils/codecs/vcf/VCFCodec.java
@@ -12,12 +12,46 @@ import java.io.FileReader;
import java.io.IOException;
import java.util.*;
-
/**
- * a feature codec for the VCF 4 specification. Our aim is to read in the records and convert to VariantContext as
- * quickly as possible, relying on VariantContext to do the validation of any contradictory (or malformed) record parameters.
+ * A feature codec for the VCF 4 specification
+ *
+ *
+ * VCF is a text file format (most likely stored in a compressed manner). It contains meta-information lines, a
+ * header line, and then data lines each containing information about a position in the genome.
+ *
+ * One of the main uses of next-generation sequencing is to discover variation amongst large populations
+ * of related samples. Recently the format for storing next-generation read alignments has been
+ * standardised by the SAM/BAM file format specification. This has significantly improved the
+ * interoperability of next-generation tools for alignment, visualisation, and variant calling.
+ * We propose the Variant Call Format (VCF) as a standarised format for storing the most prevalent
+ * types of sequence variation, including SNPs, indels and larger structural variants, together
+ * with rich annotations. VCF is usually stored in a compressed manner and can be indexed for
+ * fast data retrieval of variants from a range of positions on the reference genome.
+ * The format was developed for the 1000 Genomes Project, and has also been adopted by other projects
+ * such as UK10K, dbSNP, or the NHLBI Exome Project. VCFtools is a software suite that implements
+ * various utilities for processing VCF files, including validation, merging and comparing,
+ * and also provides a general Perl and Python API.
+ * The VCF specification and VCFtools are available from http://vcftools.sourceforge.net.
+ *
+ *
+ * See also: @see VCF specification
+ * See also: @see VCF spec. publication
+ *
+ *
+ * File format example
+ *
+ * ##fileformat=VCFv4.0
+ * #CHROM POS ID REF ALT QUAL FILTER INFO FORMAT NA12878
+ * chr1 109 . A T 0 PASS AC=1 GT:AD:DP:GL:GQ 0/1:610,327:308:-316.30,-95.47,-803.03:99
+ * chr1 147 . C A 0 PASS AC=1 GT:AD:DP:GL:GQ 0/1:294,49:118:-57.87,-34.96,-338.46:99
+ *
+ *
+ * @author Mark DePristo
+ * @since 2010
*/
public class VCFCodec extends AbstractVCFCodec {
+ // Our aim is to read in the records and convert to VariantContext as quickly as possible, relying on VariantContext to do the validation of any contradictory (or malformed) record parameters.
+
public final static String VCF4_MAGIC_HEADER = "##fileformat=VCFv4";
/**
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java
index 89163dfcb..5bbe3f91e 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeature.java
@@ -36,8 +36,12 @@ import java.lang.annotation.*;
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface DocumentedGATKFeature {
+ /** Should we actually document this feature, even through it's annotated? */
public boolean enable() default true;
+ /** The overall group name (walkers, readfilters) this feature is associated with */
public String groupName();
+ /** A human readable summary of the purpose of this group of features */
public String summary() default "";
+ /** Are there links to other docs that we should include? CommandLineGATK.class for walkers, for example? */
public Class[] extraDocs() default {};
}
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureHandler.java b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureHandler.java
index ce03c8093..87926d2e3 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureHandler.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureHandler.java
@@ -92,9 +92,7 @@ public abstract class DocumentedGATKFeatureHandler {
*
* toProcess.setHandlerContent(summary, rootMap);
*
- * @param rootDoc
* @param toProcess
- * @param all
*/
- public abstract void processOne(RootDoc rootDoc, GATKDocWorkUnit toProcess, Set all);
+ public abstract void processOne(GATKDocWorkUnit toProcess);
}
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java
index 66354202f..6c8b0a475 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java
@@ -25,12 +25,15 @@
package org.broadinstitute.sting.utils.help;
/**
- * Documentation unit. Effectively a class version of the DocumentedGATKFeature
+ * Documentation unit. Effectively a class version of the DocumentedGATKFeature.
+ * Immutable data structure.
*
* @author depristo
*/
class DocumentedGATKFeatureObject {
+ /** Which class are we documenting. Specific to each class being documented */
private final Class classToDoc;
+ /** Are we enabled? */
private final boolean enable;
private final String groupName, summary;
private final Class[] extraDocs;
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GATKDocUtils.java b/public/java/src/org/broadinstitute/sting/utils/help/GATKDocUtils.java
index 983805c4d..cd645943b 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDocUtils.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/GATKDocUtils.java
@@ -25,14 +25,33 @@
package org.broadinstitute.sting.utils.help;
public class GATKDocUtils {
+ /** The URL root for RELEASED GATKDOC units */
public final static String URL_ROOT_FOR_RELEASE_GATKDOCS = "http://www.broadinstitute.org/gsa/gatkdocs/release/";
+ /** The URL root for STABLE GATKDOC units */
public final static String URL_ROOT_FOR_STABLE_GATKDOCS = "http://iwww.broadinstitute.org/gsa/gatkdocs/stable/";
+ /** The URL root for UNSTABLE GATKDOC units */
public final static String URL_ROOT_FOR_UNSTABLE_GATKDOCS = "http://iwww.broadinstitute.org/gsa/gatkdocs/unstable/";
+ /**
+ * Return the filename of the GATKDoc HTML that would be generated for Class. This
+ * does not guarantee that the docs exist, or that docs would actually be generated
+ * for class (might not be annotated for documentation, for example). But if
+ * this class is documented, GATKDocs will write the docs to a file named as returned
+ * by this function.
+ *
+ * @param c
+ * @return
+ */
public static String htmlFilenameForClass(Class c) {
return c.getName().replace(".", "_") + ".html";
}
+ /**
+ * Returns a full URL http://etc/ linking to the documentation for class (assuming it
+ * exists). Currently points to the RELEASE doc path only.
+ * @param c
+ * @return
+ */
public static String helpLinksToGATKDocs(Class c) {
String classPath = htmlFilenameForClass(c);
StringBuilder b = new StringBuilder();
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
index 5755d2b37..7f26f22f5 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
@@ -34,23 +34,74 @@ import org.apache.commons.io.FileUtils;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.broad.tribble.FeatureCodec;
+import org.broadinstitute.sting.gatk.CommandLineGATK;
+import org.broadinstitute.sting.gatk.walkers.qc.DocumentationTest;
import org.broadinstitute.sting.utils.exceptions.ReviewedStingException;
+import org.broadinstitute.sting.utils.exceptions.UserException;
import java.io.*;
import java.util.*;
/**
+ * Javadoc Doclet that combines javadoc, GATK ParsingEngine annotations, and FreeMarker
+ * templates to produce html formatted GATKDocs for walkers
+ * and other classes.
*
+ * This document has the following workflow:
+ *
+ * 1 -- walk the javadoc heirarchy, looking for class that have the
+ * DocumentedGATKFeature annotation or are in the type heirarchy in the
+ * static list of things to document, and are to be documented
+ * 2 -- construct for each a GATKDocWorkUnit, resulting in the complete
+ * set of things to document
+ * 3 -- for each unit, actually generate an html page documenting it
+ * as well as links to related features via their units. Writing
+ * of a specific class HTML is accomplished by a generate DocumentationHandler
+ * 4 -- write out an index of all units, organized by group
+ *
+ * The documented classes are restricted to only those with @DocumentedGATKFeature
+ * annotation or are in the STATIC_DOCS class.
*/
public class GATKDoclet {
- final protected static File SETTINGS_DIR = new File("settings/helpTemplates");
- final protected static File DESTINATION_DIR = new File("gatkdocs");
final protected static Logger logger = Logger.getLogger(GATKDoclet.class);
+
+ /** Where we find the help FreeMarker templates */
+ final protected static File SETTINGS_DIR = new File("settings/helpTemplates");
+
+ /** Where we write the GATKDoc html directory */
+ final protected static File DESTINATION_DIR = new File("gatkdocs");
+
+ // ----------------------------------------------------------------------
+ //
+ // Global variables that are set on the command line by javadoc
+ //
+ // ----------------------------------------------------------------------
protected static String buildTimestamp = null, absoluteVersion = null;
protected static boolean showHiddenFeatures = false;
+ protected static boolean testOnly = false;
+
+ /**
+ * Any class that's in this list will be included in the documentation
+ * when the -test argument is provided. Useful for debugging.
+ */
+ private static final List> testOnlyKeepers = Arrays.asList(
+ DocumentationTest.class, CommandLineGATK.class, UserException.class);
+
+ /** The javadoc root doc */
RootDoc rootDoc;
+ /** The set of all things we are going to document */
+ Set myWorkUnits;
+
+ /**
+ * A static list of DocumentedGATKFeatureObjects. Any class that is as or extends
+ * one of the DocumentedGATKFeatureObjects.clazz of this collection will also
+ * be documented, even if it doesn't have the @DocumentedGATKFeature annotation. Useful
+ * when you want to document things that implement an interface (annotations on java
+ * interfaces aren't inherited) or whose base class isn't under your control (tribble
+ * codecs).
+ */
final static Collection STATIC_DOCS = new ArrayList();
static {
STATIC_DOCS.add(new DocumentedGATKFeatureObject(FeatureCodec.class,
@@ -66,7 +117,8 @@ public class GATKDoclet {
* @throws java.io.IOException if output can't be written.
*/
public static boolean start(RootDoc rootDoc) throws IOException {
- logger.setLevel(Level.DEBUG);
+ logger.setLevel(Level.INFO);
+
// load arguments
for(String[] options: rootDoc.options()) {
if(options[0].equals("-build-timestamp"))
@@ -75,10 +127,13 @@ public class GATKDoclet {
absoluteVersion = options[1];
if (options[0].equals("-include-hidden"))
showHiddenFeatures = true;
+ if (options[0].equals("-test"))
+ testOnly = true;
}
- GATKDoclet doclet = new GATKDoclet();
- doclet.processDocs(rootDoc);
+ // process the docs
+ new GATKDoclet().processDocs(rootDoc);
+
return true;
}
@@ -88,23 +143,74 @@ public class GATKDoclet {
* @return Number of potential parameters; 0 if not supported.
*/
public static int optionLength(String option) {
- if(option.equals("-build-timestamp") || option.equals("-absolute-version") || option.equals("-include-hidden")) {
+ if(option.equals("-build-timestamp") ||
+ option.equals("-absolute-version") ||
+ option.equals("-include-hidden")) {
return 2;
- }
- return 0;
+ } else if ( option.equals("-test") )
+ return 1;
+ else
+ return 0;
}
+ /**
+ * Are we supposed to include @Hidden annotations in our documented output?
+ * @return
+ */
public boolean showHiddenFeatures() {
return showHiddenFeatures;
}
- public Set workUnits() {
+ /**
+ *
+ * @param rootDoc
+ */
+ private void processDocs(RootDoc rootDoc) {
+ // setup the global access to the root
+ this.rootDoc = rootDoc;
+
+ try {
+ // basic setup
+ DESTINATION_DIR.mkdirs();
+ FileUtils.copyFile(new File(SETTINGS_DIR + "/style.css"), new File(DESTINATION_DIR + "/style.css"));
+
+ /* ------------------------------------------------------------------- */
+ /* You should do this ONLY ONCE in the whole application life-cycle: */
+
+ Configuration cfg = new Configuration();
+ // Specify the data source where the template files come from.
+ cfg.setDirectoryForTemplateLoading(SETTINGS_DIR);
+ // Specify how templates will see the data-model. This is an advanced topic...
+ cfg.setObjectWrapper(new DefaultObjectWrapper());
+
+ myWorkUnits = computeWorkUnits();
+ for ( GATKDocWorkUnit workUnit : myWorkUnits ) {
+ processDocWorkUnit(cfg, workUnit);
+ }
+
+ processIndex(cfg, new ArrayList(myWorkUnits));
+ } catch ( FileNotFoundException e ) {
+ throw new RuntimeException(e);
+ } catch ( IOException e ) {
+ throw new RuntimeException(e);
+ }
+ }
+
+ /**
+ * Returns the set of all GATKDocWorkUnits that we are going to generate docs for.
+ * @return
+ */
+ private Set computeWorkUnits() {
TreeSet m = new TreeSet();
for ( ClassDoc doc : rootDoc.classes() ) {
//logger.debug("Considering " + doc);
Class clazz = getClassForClassDoc(doc);
+ // don't add anything that's not DocumentationTest if we are in test mode
+ if ( clazz != null && testOnly && ! testOnlyKeepers.contains(clazz) )
+ continue;
+
//if ( clazz != null && clazz.getName().equals("org.broadinstitute.sting.gatk.walkers.annotator.AlleleBalance"))
// logger.debug("foo");
@@ -124,37 +230,13 @@ public class GATKDoclet {
return m;
}
- protected void processDocs(RootDoc rootDoc) {
- // setup the global access to the root
- this.rootDoc = rootDoc;
-
- try {
- // basic setup
- DESTINATION_DIR.mkdirs();
- FileUtils.copyFile(new File(SETTINGS_DIR + "/style.css"), new File(DESTINATION_DIR + "/style.css"));
-
- /* ------------------------------------------------------------------- */
- /* You should do this ONLY ONCE in the whole application life-cycle: */
-
- Configuration cfg = new Configuration();
- // Specify the data source where the template files come from.
- cfg.setDirectoryForTemplateLoading(SETTINGS_DIR);
- // Specify how templates will see the data-model. This is an advanced topic...
- cfg.setObjectWrapper(new DefaultObjectWrapper());
-
- Set myWorkUnits = workUnits();
- for ( GATKDocWorkUnit workUnit : myWorkUnits ) {
- processDocWorkUnit(cfg, workUnit, myWorkUnits);
- }
-
- processIndex(cfg, new ArrayList(myWorkUnits));
- } catch ( FileNotFoundException e ) {
- throw new RuntimeException(e);
- } catch ( IOException e ) {
- throw new RuntimeException(e);
- }
- }
-
+ /**
+ * Create a handler capable of documenting the class doc according to feature. Returns
+ * null if no appropriate handler is found or doc shouldn't be documented at all.
+ * @param doc
+ * @param feature
+ * @return
+ */
private DocumentedGATKFeatureHandler createHandler(ClassDoc doc, DocumentedGATKFeatureObject feature) {
if ( feature != null ) {
if ( feature.enable() ) {
@@ -169,6 +251,13 @@ public class GATKDoclet {
return null;
}
+ /**
+ * Returns the instantiated DocumentedGATKFeatureObject that describes the GATKDoc
+ * structure we will apply to Doc.
+ *
+ * @param doc
+ * @return null if this proves inappropriate or doc shouldn't be documented
+ */
private DocumentedGATKFeatureObject getFeatureForClassDoc(ClassDoc doc) {
Class docClass = getClassForClassDoc(doc);
@@ -188,6 +277,11 @@ public class GATKDoclet {
}
}
+ /**
+ * Return the Java class described by the ClassDoc doc
+ * @param doc
+ * @return
+ */
private Class getClassForClassDoc(ClassDoc doc) {
try {
// todo -- what do I need the ? extends Object to pass the compiler?
@@ -203,10 +297,12 @@ public class GATKDoclet {
}
}
- public static ClassDoc getClassDocForClass(RootDoc rootDoc, Class clazz) {
- return rootDoc.classNamed(clazz.getName());
- }
-
+ /**
+ * Create the html index listing all of the GATKDocs features
+ * @param cfg
+ * @param indexData
+ * @throws IOException
+ */
private void processIndex(Configuration cfg, List indexData) throws IOException {
/* Get or create a template */
Template temp = cfg.getTemplate("generic.index.template.html");
@@ -221,6 +317,12 @@ public class GATKDoclet {
}
}
+ /**
+ * Helpful function to create the html index. Given all of the already run GATKDocWorkUnits,
+ * create the high-level grouping data listing individual features by group.
+ * @param indexData
+ * @return
+ */
private Map groupIndexData(List indexData) {
//
// root -> data -> { summary -> y, filename -> z }, etc
@@ -248,6 +350,11 @@ public class GATKDoclet {
return root;
}
+ /**
+ * Trivial helper routine that returns the map of name and summary given the annotation
+ * @param annotation
+ * @return
+ */
private static final Map toMap(DocumentedGATKFeatureObject annotation) {
Map root = new HashMap();
root.put("name", annotation.groupName());
@@ -255,18 +362,39 @@ public class GATKDoclet {
return root;
}
- public final static GATKDocWorkUnit findWorkUnitForClass(Class c, Set all) {
- for ( final GATKDocWorkUnit unit : all )
+ /**
+ * Helper function that finding the GATKDocWorkUnit associated with class from among all of the work units
+ * @param c the class we are looking for
+ * @return the GATKDocWorkUnit whose .clazz.equals(c), or null if none could be found
+ */
+ public final GATKDocWorkUnit findWorkUnitForClass(Class c) {
+ for ( final GATKDocWorkUnit unit : this.myWorkUnits )
if ( unit.clazz.equals(c) )
return unit;
return null;
}
- private void processDocWorkUnit(Configuration cfg, GATKDocWorkUnit unit, Set all)
+ /**
+ * Return the ClassDoc associated with clazz
+ * @param clazz
+ * @return
+ */
+ public ClassDoc getClassDocForClass(Class clazz) {
+ return rootDoc.classNamed(clazz.getName());
+ }
+
+ /**
+ * High-level function that processes a single DocWorkUnit unit using its handler
+ *
+ * @param cfg
+ * @param unit
+ * @throws IOException
+ */
+ private void processDocWorkUnit(Configuration cfg, GATKDocWorkUnit unit)
throws IOException {
//System.out.printf("Processing documentation for class %s%n", unit.classDoc);
- unit.handler.processOne(rootDoc, unit, all);
+ unit.handler.processOne(unit);
// Get or create a template
Template temp = cfg.getTemplate(unit.handler.getTemplateName(unit.classDoc));
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
index d7add9af0..4f1e95499 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
@@ -24,6 +24,7 @@
package org.broadinstitute.sting.utils.help;
+import com.google.java.contract.Ensures;
import com.google.java.contract.Requires;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.FieldDoc;
@@ -31,8 +32,10 @@ import com.sun.javadoc.RootDoc;
import com.sun.javadoc.Tag;
import org.apache.log4j.Logger;
import org.broad.tribble.Feature;
+import org.broad.tribble.bed.FullBEDFeature;
import org.broadinstitute.sting.commandline.*;
import org.broadinstitute.sting.gatk.CommandLineGATK;
+import org.broadinstitute.sting.gatk.arguments.DbsnpArgumentCollection;
import org.broadinstitute.sting.gatk.refdata.tracks.FeatureManager;
import org.broadinstitute.sting.utils.Utils;
import org.broadinstitute.sting.utils.classloader.JVMUtils;
@@ -49,14 +52,18 @@ import java.util.*;
*/
public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
private static Logger logger = Logger.getLogger(GenericDocumentationHandler.class);
- GATKDocWorkUnit toProcess;
- ClassDoc classdoc;
- Set all;
- RootDoc rootDoc;
+
+ /**
+ * The max. length of the longest of --fullName -shortName argument name
+ * before we prefer the shorter option.
+ */
+ private static final int MAX_DISPLAY_NAME = 30;
+
+ /** The Class we are documenting */
+ private GATKDocWorkUnit toProcess;
@Override
public boolean includeInDocs(ClassDoc doc) {
-// return true;
try {
Class type = HelpUtils.getClassForDoc(doc);
return JVMUtils.isConcrete(type);
@@ -72,11 +79,8 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
}
@Override
- public void processOne(RootDoc rootDoc, GATKDocWorkUnit toProcessArg, Set allArg) {
- this.rootDoc = rootDoc;
+ public void processOne(GATKDocWorkUnit toProcessArg) {
this.toProcess = toProcessArg;
- this.all = allArg;
- this.classdoc = toProcess.classDoc;
//System.out.printf("%s class %s%n", toProcess.group, toProcess.classDoc);
Map root = new HashMap();
@@ -88,71 +92,76 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
toProcess.setHandlerContent((String)root.get("summary"), root);
}
+ /**
+ * Add high-level summary information about toProcess to root, such as its
+ * name, summary, description, version, etc.
+ *
+ * @param root
+ */
protected void addHighLevelBindings(Map root) {
- root.put("name", classdoc.name());
+ root.put("name", toProcess.classDoc.name());
// Extract overrides from the doc tags.
StringBuilder summaryBuilder = new StringBuilder();
- for(Tag tag: classdoc.firstSentenceTags())
+ for(Tag tag: toProcess.classDoc.firstSentenceTags())
summaryBuilder.append(tag.text());
root.put("summary", summaryBuilder.toString());
- root.put("description", classdoc.commentText().substring(summaryBuilder.toString().length()));
+ root.put("description", toProcess.classDoc.commentText().substring(summaryBuilder.toString().length()));
root.put("timestamp", toProcess.buildTimestamp);
root.put("version", toProcess.absoluteVersion);
- for(Tag tag: classdoc.tags()) {
+ for(Tag tag: toProcess.classDoc.tags()) {
root.put(tag.name(), tag.text());
}
}
+ /**
+ * Add bindings describing related GATK capabilites to toProcess
+ * @param root
+ */
+ protected void addRelatedBindings(Map root) {
+ List> extraDocsData = new ArrayList>();
+
+ // add in all of the explicitly related items
+ for ( final Class extraDocClass : toProcess.annotation.extraDocs() ) {
+ final GATKDocWorkUnit otherUnit = getDoclet().findWorkUnitForClass(extraDocClass);
+ if ( otherUnit == null )
+ throw new ReviewedStingException("Requested extraDocs for class without any documentation: " + extraDocClass);
+ extraDocsData.add(
+ new HashMap(){{
+ put("filename", otherUnit.filename);
+ put("name", otherUnit.name);}});
+
+ }
+ root.put("extradocs", extraDocsData);
+ }
+
+ /**
+ * Add information about all of the arguments available to toProcess to root
+ *
+ * @param root
+ */
protected void addArgumentBindings(Map root) {
ParsingEngine parsingEngine = createStandardGATKParsingEngine();
- // attempt to instantiate the class
- Object instance = makeInstanceIfPossible(toProcess.clazz);
-
- Map>> args = new HashMap>>();
+ Map>> args = createArgumentMap();
root.put("arguments", args);
- args.put("all", new ArrayList>());
- args.put("required", new ArrayList>());
- args.put("optional", new ArrayList>());
- args.put("advanced", new ArrayList>());
- args.put("hidden", new ArrayList>());
- args.put("depreciated", new ArrayList>());
try {
- for ( ArgumentSource argumentSource : parsingEngine.extractArgumentSources(HelpUtils.getClassForDoc(classdoc)) ) {
+ // loop over all of the arguments according to the parsing engine
+ for ( final ArgumentSource argumentSource : parsingEngine.extractArgumentSources(HelpUtils.getClassForDoc(toProcess.classDoc)) ) {
+ // todo -- why can you have multiple ones?
ArgumentDefinition argDef = argumentSource.createArgumentDefinitions().get(0);
- FieldDoc fieldDoc = getFieldDoc(classdoc, argumentSource.field.getName());
- Map argBindings = docForArgument(fieldDoc, argumentSource, argDef); // todo -- why can you have multiple ones?
+ FieldDoc fieldDoc = getFieldDoc(toProcess.classDoc, argumentSource.field.getName());
+ Map argBindings = docForArgument(fieldDoc, argumentSource, argDef);
if ( ! argumentSource.isHidden() || getDoclet().showHiddenFeatures() ) {
- logger.debug(String.format("Processing %s", argumentSource));
- String kind = "optional";
- if ( argumentSource.isRequired() ) kind = "required";
- else if ( argumentSource.isAdvanced() ) kind = "advanced";
- else if ( argumentSource.isHidden() ) kind = "hidden";
- else if ( argumentSource.isDeprecated() ) kind = "depreciated";
+ final String kind = docKindOfArg(argumentSource);
- // get the value of the field
- if ( instance != null ) {
- Object value = getFieldValue(toProcess.clazz, instance, fieldDoc.name());
-
- if ( value == null && argumentSource.createsTypeDefault() ) {
- // handle the case where there's an implicit default
- try {
- value = argumentSource.typeDefaultDocString();
- } catch (ReviewedStingException e) {
- ; // failed to create type default, don't worry about it
- }
- }
-
- if ( value != null )
- argBindings.put("defaultValue", prettyPrintValueString(value));
- }
+ final Object value = argumentValue(toProcess.clazz, argumentSource);
+ if ( value != null )
+ argBindings.put("defaultValue", prettyPrintValueString(value));
args.get(kind).add(argBindings);
args.get("all").add(argBindings);
- } else {
- logger.debug(String.format("Skipping hidden feature %s", argumentSource));
}
}
@@ -165,11 +174,78 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
}
}
+ /**
+ * Return the argument kind (required, advanced, hidden, etc) of this argumentSource
+ * @param argumentSource
+ * @return
+ */
+ @Requires("argumentSource != null")
+ @Ensures("result != null")
+ private String docKindOfArg(ArgumentSource argumentSource) {
+ if ( argumentSource.isRequired() ) return "required";
+ else if ( argumentSource.isAdvanced() ) return "advanced";
+ else if ( argumentSource.isHidden() ) return "hidden";
+ else if ( argumentSource.isDeprecated() ) return "depreciated";
+ else return "optional";
+ }
+
+ /**
+ * Attempts to determine the value of argumentSource in an instantiated version of c
+ * @param c
+ * @param argumentSource
+ * @return value of argumentSource, or null if this isn't possible
+ */
+ @Requires({"c != null", "argumentSource != null"})
+ private Object argumentValue(Class c, ArgumentSource argumentSource) {
+ // get the value of the field
+ // attempt to instantiate the class
+ final Object instance = makeInstanceIfPossible(toProcess.clazz);
+ if ( instance != null ) {
+ final Object value = getFieldValue(instance, argumentSource.field.getName());
+ if ( value != null )
+ return value;
+
+ if ( argumentSource.createsTypeDefault() ) {
+ try { // handle the case where there's an implicit default
+ return argumentSource.typeDefaultDocString();
+ } catch (ReviewedStingException e) {
+ ; // failed to create type default, don't worry about it
+ }
+ }
+ }
+
+ return null;
+ }
+
+ /**
+ * Create the argument map for holding class arguments
+ * @return
+ */
+ private Map>> createArgumentMap() {
+ Map>> args = new HashMap>>();
+ args.put("all", new ArrayList>());
+ args.put("required", new ArrayList>());
+ args.put("optional", new ArrayList>());
+ args.put("advanced", new ArrayList>());
+ args.put("hidden", new ArrayList>());
+ args.put("depreciated", new ArrayList>());
+ return args;
+ }
+
+
+ /**
+ * Sorts the individual argument list in unsorted according to CompareArgumentsByName
+ * @param unsorted
+ * @return
+ */
private List> sortArguments(List> unsorted) {
Collections.sort(unsorted, new CompareArgumentsByName());
return unsorted;
}
+ /**
+ * Sort arguments by case-insensitive comparison ignoring the -- and - prefixes
+ */
private class CompareArgumentsByName implements Comparator> {
public int compare(Map x, Map y) {
return elt(x).compareTo(elt(y));
@@ -186,25 +262,32 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
}
}
- private Object getFieldValue(Class c, Object instance, String fieldName) {
- Field field = JVMUtils.findField(c, fieldName);
- if ( field != null ) {
- Object value = JVMUtils.getFieldValue(field, instance);
- //System.out.printf("Fetched value of field %s in class %s: %s%n", fieldName, c, value);
- return value;
- } else {
- return findFieldValueInArgumentCollections(c, instance, fieldName);
- }
- }
-
- private Object findFieldValueInArgumentCollections(Class c, Object instance, String fieldName) {
- for ( Field field : JVMUtils.getAllFields(c) ) {
+ /**
+ * Utility function that finds the value of fieldName in any fields of ArgumentCollection fields in
+ * instance of class c.
+ *
+ * @param instance the object to query for the field value
+ * @param fieldName the name of the field we are looking for in instance
+ * @return The value assigned to field in the ArgumentCollection, otherwise null
+ */
+ private Object getFieldValue(Object instance, String fieldName) {
+ //
+ // subtle note. If you have a field named X that is an ArgumentCollection that
+ // contains a field X as well, you need only consider fields in the argumentCollection, not
+ // matching the argument itself.
+ //
+ // @ArgumentCollection
+ // protected DbsnpArgumentCollection dbsnp = new DbsnpArgumentCollection();
+ //
+ for ( Field field : JVMUtils.getAllFields(instance.getClass()) ) {
if ( field.isAnnotationPresent(ArgumentCollection.class) ) {
//System.out.printf("Searching for %s in argument collection field %s%n", fieldName, field);
Object fieldValue = JVMUtils.getFieldValue(field, instance);
- Object value = getFieldValue(fieldValue.getClass(), fieldValue, fieldName);
+ Object value = getFieldValue(fieldValue, fieldName);
if ( value != null )
return value;
+ } else if ( field.getName().equals(fieldName) ) {
+ return JVMUtils.getFieldValue(field, instance);
}
}
@@ -212,6 +295,8 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
}
/**
+ * Pretty prints value
+ *
* Assumes value != null
* @param value
* @return
@@ -246,6 +331,11 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
return value.toString();
}
+ /**
+ * Attempt to instantiate class c, if possible. Returns null if this proves impossible.
+ * @param c
+ * @return
+ */
private Object makeInstanceIfPossible(Class c) {
Object instance = null;
try {
@@ -265,47 +355,16 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
// this last one is super dangerous, but some of these methods catch ClassNotFoundExceptions
// and rethrow then as RuntimeExceptions
catch (RuntimeException e) {}
-// finally {
-// if ( instance == null )
-// logger.warn(String.format("Unable to create instance of class %s => %s", c, instance));
-// }
return instance;
}
- protected void addRelatedBindings(Map root) {
- List> extraDocsData = new ArrayList>();
- // add in all of the explicitly related items
- for ( final Class extraDocClass : toProcess.annotation.extraDocs() ) {
- final GATKDocWorkUnit otherUnit = GATKDoclet.findWorkUnitForClass(extraDocClass, all);
- if ( otherUnit == null )
- throw new ReviewedStingException("Requested extraDocs for class without any documentation: " + extraDocClass);
- extraDocsData.add(
- new HashMap(){{
- put("filename", otherUnit.filename);
- put("name", otherUnit.name);}});
-
- }
- root.put("extradocs", extraDocsData);
- }
-
- private static final String classRelationship(Class me, Class other) {
- if ( other.equals(me) )
- // no circular references
- return null;
- else if ( other.isAssignableFrom(me) )
- // toProcess is a superclass of other.clazz
- return "superclass";
- else if ( me.isAssignableFrom(other) )
- // toProcess inherits from other.clazz
- return "subclass";
- else
- return null;
-
- }
-
- protected ParsingEngine createStandardGATKParsingEngine() {
+ /**
+ * Create an instance of the GATK parsing engine, for argument processing with GATKDoclet
+ * @return
+ */
+ private ParsingEngine createStandardGATKParsingEngine() {
CommandLineProgram clp = new CommandLineGATK();
try {
CommandLineProgram.start(clp, new String[]{}, true);
@@ -315,10 +374,25 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
}
}
+ /**
+ * Gets the javadocs associated with field name in classDoc. Throws a
+ * runtime exception if this proves impossible.
+ *
+ * @param classDoc
+ * @param name
+ * @return
+ */
private FieldDoc getFieldDoc(ClassDoc classDoc, String name) {
return getFieldDoc(classDoc, name, true);
}
+ /**
+ * Recursive helper routine to getFieldDoc()
+ * @param classDoc
+ * @param name
+ * @param primary
+ * @return
+ */
private FieldDoc getFieldDoc(ClassDoc classDoc, String name, boolean primary) {
//System.out.printf("Looking for %s in %s%n", name, classDoc.name());
for ( FieldDoc fieldDoc : classDoc.fields(false) ) {
@@ -353,7 +427,14 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
return null;
}
- private static final int MAX_DISPLAY_NAME = 30;
+ /**
+ * Returns a Pair of (main, synonym) names for argument with fullName s1 and
+ * shortName s2. The main is selected to be the longest of the two, provided
+ * it doesn't exceed MAX_DISPLAY_NAME, in which case the shorter is taken.
+ * @param s1
+ * @param s2
+ * @return
+ */
Pair displayNames(String s1, String s2) {
if ( s1 == null ) return new Pair(s2, null);
if ( s2 == null ) return new Pair(s1, null);
@@ -367,6 +448,15 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
return new Pair(l, s);
}
+ /**
+ * Returns a human readable string that describes the Type type of a GATK argument.
+ *
+ * This will include parameterized types, so that Set{T} shows up as Set(T) and not
+ * just Set in the docs.
+ *
+ * @param type
+ * @return
+ */
protected String argumentTypeString(Type type) {
if (type instanceof ParameterizedType) {
ParameterizedType parameterizedType = (ParameterizedType)type;
@@ -385,6 +475,13 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
}
}
+ /**
+ * Helper routine that returns the Feature.class required by a RodBinding,
+ * either T for RodBinding{T} or List{RodBinding{T}}. Returns null if
+ * the Type doesn't fit either model.
+ * @param type
+ * @return
+ */
protected Class getFeatureTypeIfPossible(Type type) {
if ( type instanceof ParameterizedType) {
ParameterizedType paramType = (ParameterizedType)type;
@@ -402,6 +499,14 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
return null;
}
+ /**
+ * High-level entry point for creating a FreeMarker map describing the GATK argument
+ * source with definition def, with associated javadoc fieldDoc.
+ * @param fieldDoc
+ * @param source
+ * @param def
+ * @return a non-null Map binding argument keys with their values
+ */
protected Map docForArgument(FieldDoc fieldDoc, ArgumentSource source, ArgumentDefinition def) {
Map root = new HashMap();
Pair names = displayNames("-" + def.shortName, "--" + def.fullName);
@@ -434,27 +539,29 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
root.put("summary", def.doc != null ? def.doc : "");
root.put("fulltext", fieldDoc.commentText());
+ // What are our enum options?
+ if ( def.validOptions != null )
+ root.put("options", docForEnumArgument(source.field.getType()));
+
+ // general attributes
List attributes = new ArrayList();
- // this one below is just too much.
- //attributes.add(def.ioType.annotationClass.getSimpleName());
if ( def.required ) attributes.add("required");
- // flag is just boolean, not interesting
- //if ( def.isFlag ) attributes.add("flag");
- if ( def.isHidden ) attributes.add("hidden");
if ( source.isDeprecated() ) attributes.add("depreciated");
if ( attributes.size() > 0 )
root.put("attributes", Utils.join(", ", attributes));
- if ( def.validOptions != null ) {
- root.put("options", docForEnumArgument(source.field.getType()));
- }
-
return root;
}
+ /**
+ * Helper routine that provides a FreeMarker map for an enumClass, grabbing the
+ * values of the enum and their associated javadoc documentation.
+ * @param enumClass
+ * @return
+ */
@Requires("enumClass.isEnum()")
private List> docForEnumArgument(Class enumClass) {
- ClassDoc doc = GATKDoclet.getClassDocForClass(rootDoc, enumClass);
+ ClassDoc doc = this.getDoclet().getClassDocForClass(enumClass);
if ( doc == null ) // || ! doc.isEnum() )
throw new RuntimeException("Tried to get docs for enum " + enumClass + " but got instead: " + doc);
@@ -468,5 +575,4 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
return bindings;
}
-
}
diff --git a/public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java b/public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java
index d72d2e83c..645ab34c1 100644
--- a/public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java
+++ b/public/java/src/org/broadinstitute/sting/utils/help/HelpUtils.java
@@ -32,14 +32,6 @@ import org.broadinstitute.sting.utils.classloader.JVMUtils;
import java.lang.reflect.Field;
public class HelpUtils {
-
- protected static boolean implementsInterface(ProgramElementDoc classDoc, Class... interfaceClasses) {
- for (Class interfaceClass : interfaceClasses)
- if (assignableToClass(classDoc, interfaceClass, false))
- return true;
- return false;
- }
-
protected static boolean assignableToClass(ProgramElementDoc classDoc, Class lhsClass, boolean requireConcrete) {
try {
Class type = getClassForDoc(classDoc);
diff --git a/public/java/test/org/broadinstitute/sting/gatk/walkers/ClipReadsWalkersIntegrationTest.java b/public/java/test/org/broadinstitute/sting/gatk/walkers/ClipReadsWalkersIntegrationTest.java
index a129f8adf..1565c419b 100755
--- a/public/java/test/org/broadinstitute/sting/gatk/walkers/ClipReadsWalkersIntegrationTest.java
+++ b/public/java/test/org/broadinstitute/sting/gatk/walkers/ClipReadsWalkersIntegrationTest.java
@@ -37,8 +37,8 @@ public class ClipReadsWalkersIntegrationTest extends WalkerTest {
"-R " + hg18Reference +
" -T ClipReads " +
"-I " + validationDataLocation + "clippingReadsTest.bam " +
- "-o %s " +
- "-ob %s " + args,
+ "-os %s " +
+ "-o %s " + args,
2, // just one output file
Arrays.asList("tmp", "bam"),
Arrays.asList(md51, md52));
@@ -72,9 +72,9 @@ public class ClipReadsWalkersIntegrationTest extends WalkerTest {
" -I " + validationDataLocation + "originalQuals.chr1.1-1K.bam" +
" -L chr1:1-1,000" +
" -OQ -QT 4 -CR WRITE_Q0S" +
- " -o %s -ob %s",
+ " -o %s -os %s",
2,
- Arrays.asList("55c01ccc2e84481b22d3632cdb06c8ba", "22db22749f811d30216215e047461621"));
+ Arrays.asList("22db22749f811d30216215e047461621", "55c01ccc2e84481b22d3632cdb06c8ba"));
executeTest("clipOriginalQuals", spec);
}
}
diff --git a/settings/helpTemplates/style.css b/settings/helpTemplates/style.css
index 375df2f51..297cd49ef 100644
--- a/settings/helpTemplates/style.css
+++ b/settings/helpTemplates/style.css
@@ -85,25 +85,33 @@ hr
* enum DT layout
*/
+dl {
+ margin-left: 3em;
+}
+
dl.enum {
margin-left: 3em;
border: 1px dashed #ccc;
}
-dt.enum {
+dt, dt.enum {
font-weight: bold;
text-decoration: underline;
}
-dd.enum {
+/*
+dt, dd.enum {
padding: 0 0 0.5em 0;
}
+*/
pre {
border: thin solid lightgray;
margin-left: 1em;
margin-right: 4em;
+/*
background-color: #e0fdff;
+*/
}
/*
* clean table layouts