Inline enum documentation is working

public/java/src/org/broadinstitute/sting/gatk/walkers/diffengine/DiffObjectsWalker.java

@@ -190,7 +190,12 @@ public class DiffObjectsWalker extends RodWalker<Integer, Integer> {
     @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();
 

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<GATKDoclet.DocWorkUnit> all);
+    public abstract void processOne(RootDoc rootDoc, GATKDoclet.DocWorkUnit toProcess, Set<GATKDoclet.DocWorkUnit> all);
 }

public/java/src/org/broadinstitute/sting/utils/help/GATKDoc.java

@@ -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<String> synonyms;
-    String summary, fulltext;
-    final Map<String, String> 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<String>(), NA_STRING, NA_STRING, new HashMap<String, String>());
-    }
-
-    public GATKDoc(DocType type, String name, List<String> synonyms, String summary, String fulltext, Map<String, String> tags) {
-        this.type = type;
-        this.name = name;
-        this.synonyms = synonyms;
-        this.summary = summary;
-        this.fulltext = fulltext;
-        this.tags = tags;
-    }
-
-    public Map<String, String> toDataModel() {
-        Map<String, String> model = new HashMap<String, String>();
-        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<String> 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);
-    }
-}

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<DocWorkUnit> 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));

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<GATKDoclet.DocWorkUnit> 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<GATKDoclet.DocWorkUnit> allArg) {
+    public void processOne(RootDoc rootDoc, GATKDoclet.DocWorkUnit toProcessArg, Set<GATKDoclet.DocWorkUnit> 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<String, Object> 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(kind).add(argBindings);
-                args.get("all").add(doc.toDataModel());
+                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) {
+    protected Map<String, Object> docForArgument(FieldDoc fieldDoc, ArgumentSource source, ArgumentDefinition def) {
-        final String name = def.fullName != null ? "--" + def.fullName : "-" + def.shortName;
+        Map<String, Object> root = new HashMap<String, Object>();
-        GATKDoc doc = new GATKDoc(GATKDoc.DocType.WALKER_ARG, name);
+        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");
+        root.put("required", def.required ? "yes" : "no");
-        doc.addTag("type", def.argumentType.getSimpleName());
+        root.put("type", def.argumentType.getSimpleName());
-        if ( def.doc != null ) doc.setSummary(def.doc);
+
+        // summary and fulltext
+        root.put("summary", def.doc != null ? def.doc : "");
+        root.put("fulltext", fieldDoc.commentText());
 
         List<String> attributes = new ArrayList<String>();
         // 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();
+            root.put("options", docForEnumArgument(source.field.getType()));
-            // todo -- what's the best way to link to these docs?  Maybe a separate section on enums?
-            doc.addTag("options", Utils.join(", ", def.validOptions));
         }
 
-        doc.setFulltext(fieldDoc.commentText().equals("") ? GATKDoc.NA_STRING : fieldDoc.commentText());
+        return root;
-
-        return doc;
     }
+
+    @Requires("enumClass.isEnum()")
+    private List<Map<String, Object>> 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<Map<String, Object>> bindings = new ArrayList<Map<String, Object>>();
+        for (final FieldDoc field : doc.fields(false) ) {
+            bindings.add(
+                    new HashMap<String, Object>(){{
+                        put("name", field.name());
+                        put("summary", field.commentText());}});
+        }
+
+        return bindings;
+    }
+
 }

settings/helpTemplates/generic.template.html

@@ -6,7 +6,7 @@
         <#list myargs as arg>
             <tr>
                 <td><a href="#${arg.name}">${arg.name}</a></td>
-                <td><a href="#${arg.name}">${arg.synonyms}</a></td>
+                <td><a href="#${arg.name}">${arg.synonyms!""}</a></td>
                 <td>${arg.type}</td>
                 <td>${arg.summary}</td>
             </tr>
@@ -18,10 +18,18 @@
 </#macro>    
    
 <#macro argumentDetails arg>
-    <h3><a name="${arg.name}">${arg.name} / ${arg.synonyms}</a>
+    <h3><a name="${arg.name}">${arg.name}<#if arg.synonyms??> / ${arg.synonyms}</#if></a>
     (<#if arg.attributes??>${arg.attributes} </#if>${arg.type})</h3>
     ${arg.summary}. ${arg.fulltext}<br>
-    <#if arg.options??>TODO: document enum in line here.  Possible values ${arg.options}</#if>
+    <#if arg.options??>
+        <p>Argument is an enumerated type with the following possible values:</p>
+        <dl class="enum">
+        <#list arg.options as option>
+            <dt>${option.name}
+            <dd>${option.summary}
+        </#list>
+        </dl>
+    </#if>
 </#macro>     
    
 <#macro relatedByType name type>

settings/helpTemplates/style.css

@@ -19,9 +19,26 @@ p.version, p.see-also
 	font-size: 8pt;
 }
 
-dt
+dl.enum
-{ 
+{
-	padding-bottom: 6pt;
+	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;
 }
 
 /*