zzh
/
gatk-3.8
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improvements to GATKDocs 

-- Now supports a static list of root classes / interfaces that should receive docs.  A complementary approach to documenting features to the DocumentedGATKFeature annotation
-- Tribble codecs are now documented!
-- No longer displayed sub and super classes
This commit is contained in:
Mark DePristo 2011-08-18 14:00:09 -04:00
parent e03db30ca0
commit 5772766dd5
3 changed files with 53 additions and 30 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
public/java/src/org/broadinstitute/sting/utils/help/DocumentedGATKFeatureObject.java
View File

@ -30,17 +30,24 @@ package org.broadinstitute.sting.utils.help;
* @author depristo
*/
class DocumentedGATKFeatureObject {
final boolean enable;
final String groupName, summary;
final Class[] extraDocs;
private final Class classToDoc;
private final boolean enable;
private final String groupName, summary;
private final Class[] extraDocs;
public DocumentedGATKFeatureObject(final boolean enable, final String groupName, final String summary, final Class[] extraDocs) {
public DocumentedGATKFeatureObject(Class classToDoc, final boolean enable, final String groupName, final String summary, final Class[] extraDocs) {
this.classToDoc = classToDoc;
this.enable = enable;
this.groupName = groupName;
this.summary = summary;
this.extraDocs = extraDocs;
}
public DocumentedGATKFeatureObject(Class classToDoc, final String groupName, final String summary) {
this(classToDoc, true, groupName, summary, new Class[]{});
}
public Class getClassToDoc() { return classToDoc; }
public boolean enable() { return enable; }
public String groupName() { return groupName; }
public String summary() { return summary; }

40
public/java/src/org/broadinstitute/sting/utils/help/GATKDoclet.java
View File

@ -33,6 +33,7 @@ import freemarker.template.TemplateException;
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.utils.exceptions.ReviewedStingException;
import java.io.*;
@ -50,6 +51,14 @@ public class GATKDoclet {
RootDoc rootDoc;
final static Collection<DocumentedGATKFeatureObject> STATIC_DOCS = new ArrayList<DocumentedGATKFeatureObject>();
static {
STATIC_DOCS.add(new DocumentedGATKFeatureObject(FeatureCodec.class,
"Reference ordered data (ROD) codecs",
"Tribble codecs for reading reference ordered data such as VCF or BED files"));
}
/**
* Extracts the contents of certain types of javadoc and adds them to an XML file.
* @param rootDoc The documentation root.
@ -162,12 +171,20 @@ public class GATKDoclet {
private DocumentedGATKFeatureObject getFeatureForClassDoc(ClassDoc doc) {
Class<? extends Object> docClass = getClassForClassDoc(doc);
// todo -- add looked here to static TO DOC collection as well
if ( docClass != null && docClass.isAnnotationPresent(DocumentedGATKFeature.class) ) {
DocumentedGATKFeature f = docClass.getAnnotation(DocumentedGATKFeature.class);
return new DocumentedGATKFeatureObject(f.enable(), f.groupName(), f.summary(), f.extraDocs());
} else {
if ( docClass == null )
return null; // not annotated so it shouldn't be documented
if ( docClass.isAnnotationPresent(DocumentedGATKFeature.class) ) {
DocumentedGATKFeature f = docClass.getAnnotation(DocumentedGATKFeature.class);
return new DocumentedGATKFeatureObject(docClass, f.enable(), f.groupName(), f.summary(), f.extraDocs());
} else {
for ( DocumentedGATKFeatureObject staticDocs : STATIC_DOCS ) {
if ( staticDocs.getClassToDoc().isAssignableFrom(docClass) ) {
return new DocumentedGATKFeatureObject(docClass, staticDocs.enable(), staticDocs.groupName(), staticDocs.summary(), staticDocs.extraDocs());
}
}
return null;
}
}
@ -212,16 +229,15 @@ public class GATKDoclet {
Collections.sort(indexData);
Set<DocumentedGATKFeatureObject> docFeatures = new HashSet<DocumentedGATKFeatureObject>();
List<Map<String, String>> groups = new ArrayList<Map<String, String>>();
Set<String> seenDocumentationFeatures = new HashSet<String>();
List<Map<String, String>> data = new ArrayList<Map<String, String>>();
for ( GATKDocWorkUnit workUnit : indexData ) {
data.add(workUnit.indexDataMap());
docFeatures.add(workUnit.annotation);
}
List<Map<String, String>> groups = new ArrayList<Map<String, String>>();
for ( DocumentedGATKFeatureObject feature : docFeatures ) {
groups.add(toMap(feature));
if ( ! seenDocumentationFeatures.contains(workUnit.annotation.groupName()) ) {
groups.add(toMap(workUnit.annotation));
seenDocumentationFeatures.add(workUnit.annotation.groupName());
}
}
root.put("data", data);

28
public/java/src/org/broadinstitute/sting/utils/help/GenericDocumentationHandler.java
View File

@ -255,21 +255,21 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
put("name", otherUnit.name);}});
}
List<Map<String, Object>> hierarchyDocs = new ArrayList<Map<String, Object>>();
for (final GATKDocWorkUnit other : all ) {
final String relation = classRelationship(toProcess.clazz, other.clazz);
if ( relation != null )
hierarchyDocs.add(
new HashMap<String, Object>(){{
put("filename", other.filename);
put("relation", relation);
put("name", other.name);}});
}
root.put("relatedDocs", hierarchyDocs);
root.put("extradocs", extraDocsData);
// List<Map<String, Object>> hierarchyDocs = new ArrayList<Map<String, Object>>();
// for (final GATKDocWorkUnit other : all ) {
// final String relation = classRelationship(toProcess.clazz, other.clazz);
// if ( relation != null )
// hierarchyDocs.add(
// new HashMap<String, Object>(){{
// put("filename", other.filename);
// put("relation", relation);
// put("name", other.name);}});
//
// }
// root.put("relatedDocs", hierarchyDocs);
}
private static final String classRelationship(Class me, Class other) {