diff --git a/public/java/src/org/broadinstitute/sting/gatk/walkers/diffengine/DiffObjectsWalker.java b/public/java/src/org/broadinstitute/sting/gatk/walkers/diffengine/DiffObjectsWalker.java index f80e85708..c660bda36 100644 --- a/public/java/src/org/broadinstitute/sting/gatk/walkers/diffengine/DiffObjectsWalker.java +++ b/public/java/src/org/broadinstitute/sting/gatk/walkers/diffengine/DiffObjectsWalker.java @@ -190,7 +190,12 @@ public class DiffObjectsWalker extends RodWalker { @Argument(fullName="testDepreciates", doc="Y", required=false) int dontUseMe = 1; - public enum TestEnum { ONE, TWO }; + public enum TestEnum { + /** Docs for ONE */ + ONE, + /** Docs for TWO */ + TWO + }; final DiffEngine diffEngine = new DiffEngine(); 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 f25a02bb5..198b09ebc 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureHandler.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureHandler.java @@ -52,5 +52,5 @@ public abstract class DocumentedGATKFeatureHandler { } public abstract String getTemplateName(ClassDoc doc) throws IOException; - public abstract void processOne(GATKDoclet.DocWorkUnit toProcess, Set all); + public abstract void processOne(RootDoc rootDoc, GATKDoclet.DocWorkUnit toProcess, Set all); } diff --git a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoc.java b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoc.java deleted file mode 100644 index 0c575523e..000000000 --- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoc.java +++ /dev/null @@ -1,123 +0,0 @@ -/* - * Copyright (c) 2011, The Broad Institute - * - * Permission is hereby granted, free of charge, to any person - * obtaining a copy of this software and associated documentation - * files (the "Software"), to deal in the Software without - * restriction, including without limitation the rights to use, - * copy, modify, merge, publish, distribute, sublicense, and/or sell - * copies of the Software, and to permit persons to whom the - * Software is furnished to do so, subject to the following - * conditions: - * - * The above copyright notice and this permission notice shall be - * included in all copies or substantial portions of the Software. - * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, - * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES - * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND - * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT - * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, - * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING - * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - * OTHER DEALINGS IN THE SOFTWARE. - */ - -package org.broadinstitute.sting.utils.help; - -import org.broadinstitute.sting.utils.Utils; - -import java.util.ArrayList; -import java.util.HashMap; -import java.util.List; -import java.util.Map; - -/** - * Created by IntelliJ IDEA. - * User: depristo - * Date: 7/21/11 - * Time: 8:51 AM - * - * Common documentation information about an GATK capability - */ -public class GATKDoc { - final DocType type; - final String name; - List synonyms; - String summary, fulltext; - final Map tags; - - public final static String NA_STRING = "None provided"; - - public enum DocType { - WALKER ("Walker"), - WALKER_ARG ("Walker argument"), - READ_FILTER ("Read filter"), - ENGINE_FEATURE ("Engine feature"); - - private final String name; - DocType(String name) { - this.name = name; - } - - }; - - public GATKDoc(DocType type, String name) { - this(type, name, new ArrayList(), NA_STRING, NA_STRING, new HashMap()); - } - - public GATKDoc(DocType type, String name, List synonyms, String summary, String fulltext, Map tags) { - this.type = type; - this.name = name; - this.synonyms = synonyms; - this.summary = summary; - this.fulltext = fulltext; - this.tags = tags; - } - - public Map toDataModel() { - Map model = new HashMap(); - model.put("type", type.name); - model.put("name", name); - model.put("synonyms", Utils.join(",", synonyms)); - model.put("summary", summary); - model.put("fulltext", fulltext); - model.putAll(tags); - return model; - } - - public DocType getType() { - return type; - } - - public String getName() { - return name; - } - - public List getSynonyms() { - return synonyms; - } - - public void addSynonym(String synonyms) { - this.synonyms.add(synonyms); - } - - public String getSummary() { - return summary; - } - - public void setSummary(String summary) { - this.summary = summary; - } - - public String getFulltext() { - return fulltext; - } - - public void setFulltext(String fulltext) { - this.fulltext = fulltext; - } - - public void addTag(String key, String value) { - this.tags.put(key, value); - } -} 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 c1dd843ac..db7d6651d 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java @@ -210,6 +210,10 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet { } } + public static ClassDoc getClassDocForClass(RootDoc rootDoc, Class clazz) { + return rootDoc.classNamed(clazz.getName()); + } + private void processIndex(Configuration cfg, List indexData) throws IOException { /* Get or create a template */ Template temp = cfg.getTemplate("generic.index.template.html"); @@ -270,7 +274,7 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet { throws IOException { System.out.printf("Processing documentation for class %s%n", unit.classDoc); - unit.handler.processOne(unit, all); + unit.handler.processOne(rootDoc, unit, all); // 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 6d982daf0..ff54a115c 100644 --- a/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java +++ b/public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java @@ -24,8 +24,10 @@ package org.broadinstitute.sting.utils.help; +import com.google.java.contract.Requires; import com.sun.javadoc.ClassDoc; import com.sun.javadoc.FieldDoc; +import com.sun.javadoc.RootDoc; import com.sun.javadoc.Tag; import org.broadinstitute.sting.commandline.*; import org.broadinstitute.sting.gatk.CommandLineGATK; @@ -44,6 +46,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { GATKDoclet.DocWorkUnit toProcess; ClassDoc classdoc; Set all; + RootDoc rootDoc; @Override public boolean shouldBeProcessed(ClassDoc doc) { @@ -63,7 +66,8 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { } @Override - public void processOne(GATKDoclet.DocWorkUnit toProcessArg, Set allArg) { + public void processOne(RootDoc rootDoc, GATKDoclet.DocWorkUnit toProcessArg, Set allArg) { + this.rootDoc = rootDoc; this.toProcess = toProcessArg; this.all = allArg; this.classdoc = toProcess.classDoc; @@ -109,13 +113,13 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { for ( ArgumentSource argumentSource : parsingEngine.extractArgumentSources(HelpUtils.getClassForDoc(classdoc)) ) { ArgumentDefinition argDef = argumentSource.createArgumentDefinitions().get(0); FieldDoc fieldDoc = getFieldDoc(classdoc, argumentSource.field.getName()); - GATKDoc doc = docForArgument(fieldDoc, argumentSource, argDef); // todo -- why can you have multiple ones? + Map argBindings = docForArgument(fieldDoc, argumentSource, argDef); // todo -- why can you have multiple ones? String kind = "optional"; if ( argumentSource.isRequired() ) kind = "required"; else if ( argumentSource.isHidden() ) kind = "hidden"; else if ( argumentSource.isDeprecated() ) kind = "depreciated"; - args.get(kind).add(doc.toDataModel()); - args.get("all").add(doc.toDataModel()); + args.get(kind).add(argBindings); + args.get("all").add(argBindings); System.out.printf("Processing %s%n", argumentSource); } } catch ( ClassNotFoundException e ) { @@ -215,16 +219,19 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { return null; } - protected GATKDoc docForArgument(FieldDoc fieldDoc, ArgumentSource source, ArgumentDefinition def) { - final String name = def.fullName != null ? "--" + def.fullName : "-" + def.shortName; - GATKDoc doc = new GATKDoc(GATKDoc.DocType.WALKER_ARG, name); + protected Map docForArgument(FieldDoc fieldDoc, ArgumentSource source, ArgumentDefinition def) { + Map root = new HashMap(); + root.put("name", def.fullName != null ? "--" + def.fullName : "-" + def.shortName); if ( def.fullName != null && def.shortName != null) - doc.addSynonym("-" + def.shortName); + root.put("synonyms", def.fullName != null ? "--" + def.fullName : "-" + def.shortName); - doc.addTag("required", def.required ? "yes" : "no"); - doc.addTag("type", def.argumentType.getSimpleName()); - if ( def.doc != null ) doc.setSummary(def.doc); + root.put("required", def.required ? "yes" : "no"); + root.put("type", def.argumentType.getSimpleName()); + + // summary and fulltext + root.put("summary", def.doc != null ? def.doc : ""); + root.put("fulltext", fieldDoc.commentText()); List attributes = new ArrayList(); // this one below is just too much. @@ -235,16 +242,30 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler { if ( def.isHidden ) attributes.add("hidden"); if ( source.isDeprecated() ) attributes.add("depreciated"); if ( attributes.size() > 0 ) - doc.addTag("attributes", Utils.join(", ", attributes)); + root.put("attributes", Utils.join(", ", attributes)); if ( def.validOptions != null ) { - //source.field.getType().isEnum(); - // todo -- what's the best way to link to these docs? Maybe a separate section on enums? - doc.addTag("options", Utils.join(", ", def.validOptions)); + root.put("options", docForEnumArgument(source.field.getType())); } - doc.setFulltext(fieldDoc.commentText().equals("") ? GATKDoc.NA_STRING : fieldDoc.commentText()); - - return doc; + return root; } + + @Requires("enumClass.isEnum()") + private List> docForEnumArgument(Class enumClass) { + ClassDoc doc = GATKDoclet.getClassDocForClass(rootDoc, enumClass); + if ( doc == null ) // || ! doc.isEnum() ) + throw new RuntimeException("Tried to get docs for enum " + enumClass + " but got instead: " + doc); + + List> bindings = new ArrayList>(); + for (final FieldDoc field : doc.fields(false) ) { + bindings.add( + new HashMap(){{ + put("name", field.name()); + put("summary", field.commentText());}}); + } + + return bindings; + } + } diff --git a/settings/helpTemplates/generic.template.html b/settings/helpTemplates/generic.template.html index 108d6ad5c..b8a392686 100644 --- a/settings/helpTemplates/generic.template.html +++ b/settings/helpTemplates/generic.template.html @@ -6,7 +6,7 @@ <#list myargs as arg> ${arg.name} - ${arg.synonyms} + ${arg.synonyms!""} ${arg.type} ${arg.summary} @@ -18,10 +18,18 @@ <#macro argumentDetails arg> -

${arg.name} / ${arg.synonyms} +

${arg.name}<#if arg.synonyms??> / ${arg.synonyms} (<#if arg.attributes??>${arg.attributes} ${arg.type})

${arg.summary}. ${arg.fulltext}
- <#if arg.options??>TODO: document enum in line here. Possible values ${arg.options} + <#if arg.options??> +

Argument is an enumerated type with the following possible values:

+
+ <#list arg.options as option> +
${option.name} +
${option.summary} + +
+ <#macro relatedByType name type> diff --git a/settings/helpTemplates/style.css b/settings/helpTemplates/style.css index 85ecf8a02..70aadcf79 100644 --- a/settings/helpTemplates/style.css +++ b/settings/helpTemplates/style.css @@ -19,9 +19,26 @@ p.version, p.see-also font-size: 8pt; } -dt -{ - padding-bottom: 6pt; +dl.enum +{ + margin: 0em 0; + padding: 0; +} + +.enum dt +{ + position: relative; + left: 0; + top: 1.1em; + width: 5em; + font-weight: bold; +} + +.enum dd +{ + border-left: 1px solid #000; + margin: 0 0 0 6em; + padding: 0 0 .5em .5em; } /*