Inline enum documentation is working
This commit is contained in:
Mark DePristo
parent
793e7d3d1d
commit
c620d96c96
|
|
@ -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();
|
||||
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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);
|
||||
}
|
||||
}
|
||||
|
|
@ -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));
|
||||
|
|
|
|||
|
|
@ -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("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<String, Object> docForArgument(FieldDoc fieldDoc, ArgumentSource source, ArgumentDefinition def) {
|
||||
Map<String, Object> root = new HashMap<String, Object>();
|
||||
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<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();
|
||||
// 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<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;
|
||||
}
|
||||
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
}
|
||||
|
||||
/*
|
||||
|
|
|
|||
Loading…
Reference in New Issue