Added GATKDocs fct to indicate default Read Filters for each tool

-- Added getClazzAnnotations() as hub to retrieve various annotations values and class properties through reflection
-- Added getReadFilters() method to retrieve Read Filter annotations
-- getReadFilters() uses recursion to walk up the inheritance to also capture superclass annotations
-- getClazzAnnotations() stores collected info in doc handler root, which is unit.forTemplate in Doclet
-- Modified FreeMarker template to use the Readfilters info (displayed after arg table, before additional capabilities)
-- Tadaaa :-) #GSATDG-63 resolve

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

@@ -224,7 +224,7 @@ public class GATKDoclet {
             File forumKeyFile = new File(FORUM_KEY_FILE);
             if (forumKeyFile.exists()) {
                 String forumKey = null;
-                // Read ing a one-line file so we can do a for loop
+                // Read in a one-line file so we can do a for loop
                 for (String line : new XReadLines(forumKeyFile))
                     forumKey = line;
                 updateForum(myWorkUnits, forumKey);
@@ -283,7 +283,7 @@ public class GATKDoclet {
             DocumentedGATKFeatureObject feature = getFeatureForClassDoc(doc);
             DocumentedGATKFeatureHandler handler = createHandler(doc, feature);
             if (handler != null && handler.includeInDocs(doc)) {
-                logger.info("Generating documentation for class " + doc);
+                //logger.info("Generating documentation for class " + doc);
                 String filename = handler.getDestinationFilename(doc, clazz);
                 GATKDocWorkUnit unit = new GATKDocWorkUnit(doc.name(),
                         filename, feature.groupName(), feature, handler, doc, clazz,

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

@@ -35,6 +35,7 @@ import org.broad.tribble.Feature;
 import org.broadinstitute.sting.commandline.*;
 import org.broadinstitute.sting.gatk.CommandLineGATK;
 import org.broadinstitute.sting.gatk.refdata.tracks.FeatureManager;
+import org.broadinstitute.sting.gatk.walkers.ReadFilters;
 import org.broadinstitute.sting.utils.Utils;
 import org.broadinstitute.sting.utils.classloader.JVMUtils;
 import org.broadinstitute.sting.utils.collections.Pair;
@@ -42,6 +43,7 @@ import org.broadinstitute.sting.utils.exceptions.ReviewedStingException;
 import org.broadinstitute.sting.utils.exceptions.StingException;
 
 import java.io.IOException;
+import java.lang.annotation.Annotation;
 import java.lang.reflect.*;
 import java.util.*;
 
@@ -91,6 +93,9 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
         addRelatedBindings(root);
         root.put("group", toProcess.group);
 
+        // Adding in retrieval of peripheral info (rf annotations etc)
+        getClazzAnnotations(toProcess.clazz, root);
+
         toProcess.setHandlerContent((String) root.get("summary"), root);
     }
 
@@ -135,7 +140,6 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
                         put("filename", otherUnit.filename);
                         put("name", otherUnit.name);
                     }});
-
         }
         root.put("extradocs", extraDocsData);
     }
@@ -270,6 +274,66 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
         }
     }
 
+    /**
+     * Umbrella function that groups the collection of values for specific annotations applied to an
+     * instance of class c. Lists of collected values are added directly to the "toProcess" object.
+     * Requires being able to instantiate the class.
+     *
+     * @param classToProcess the object to instantiate and query for the annotation
+     * @param root the root of the document handler, to which we'll store collected annotations
+     */
+    private void getClazzAnnotations(Class classToProcess, Map<String, Object> root) {
+        //
+        // attempt to instantiate the class
+        final Object instance = makeInstanceIfPossible(classToProcess);
+        if (instance != null) {
+            final Class myClass = instance.getClass();
+            // TODO: get top relevant superclass (last before object? abstract?)
+            // TODO: get parallelism options (TreeReducible or Nanoschedulable)
+            // Get read filter annotations (ReadFilters)
+            final HashSet<HashMap<String, Object>> bucket= new HashSet<HashMap<String, Object>>();
+            bucket.addAll(getReadFilters(myClass, bucket));
+            root.put("readfilters", bucket);
+            // TODO: get annotators (AnnotatorCompatible)
+            // anything else?
+        } else {
+            root.put("readfilters", new ArrayList<HashMap<String, Object>>());  // put empty list to avoid blowups
+        }
+    }
+
+
+    /**
+     * Utility function that finds the values of ReadFilters annotation applied to an instance of class c.
+     *
+     * @param myClass the class to query for the annotation
+     * @param bucket a container in which we store the annotations collected
+     * @return a list of values, otherwise null
+     */
+    private HashSet<HashMap<String, Object>> getReadFilters(Class myClass, HashSet<HashMap<String, Object>> bucket) {
+        //
+        // Retrieve annotation
+        if (myClass.isAnnotationPresent(ReadFilters.class)) {
+            final Annotation thisAnnotation = myClass.getAnnotation(ReadFilters.class);
+            if(thisAnnotation instanceof ReadFilters) {
+                final ReadFilters rfAnnotation = (ReadFilters) thisAnnotation;
+                for (Class<?> filter : rfAnnotation.value()) {
+                    // make hashmap of simplename and url
+                    final HashMap<String, Object> nugget = new HashMap<String, Object>();
+                    nugget.put("name", filter.getSimpleName());
+                    nugget.put("filename", GATKDocUtils.htmlFilenameForClass(filter));
+                    bucket.add(nugget);
+                }
+            }
+        }
+        // Look up superclasses recursively
+        final Class mySuperClass = myClass.getSuperclass();
+        if (mySuperClass.getSimpleName().equals("Object")) {
+            return bucket;
+        }
+        return getReadFilters(mySuperClass, bucket);
+    }
+
+
     /**
      * Utility function that finds the value of fieldName in any fields of ArgumentCollection fields in
      * instance of class c.
@@ -287,6 +351,7 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
         // @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);

settings/helpTemplates/generic.template.html

@@ -71,7 +71,6 @@
         </#if>
     </p>
 </#macro>
-
 <#macro relatedByType name type>
     <#list relatedDocs as relatedDoc>
         <#if relatedDoc.relation == type>
@@ -143,12 +142,27 @@
         </#if>
 
         <#-- Create references to additional capabilities if appropriate -->
+        	<#if readfilters?size != 0>
+        		<hr>
+        		<h3>Read Filters</h3>
+        		<#if readfilters?size = 1>
+        			<p>This Read Filter is automatically applied to the data by the Engine before processing by ${name}.</p>
+        		</#if>
+        		<#if (readfilters?size > 1) >
+        			<p>These Read Filters are automatically applied to the data by the Engine before processing by ${name}.</p>
+        		</#if>
+        		<ul>
+					<#list readfilters as filter>
+						<li><a href="${filter.filename}">${filter.name}</a></li>	
+					</#list>
+        		</ul>
+        	</#if>
             <#if extradocs?size != 0>
                 <hr>
                 <h2>Additional capabilities</h2>
-                The arguments described in the entries below can be supplied to this tool to modify
+                <p>The arguments described in the entries below can be supplied to this tool to modify
                 its behavior. For example, the -L argument directs the GATK engine restricts processing
-                to specific genomic intervals. This capability is available to all GATK walkers.
+                to specific genomic intervals (this is an Engine capability and is therefore available to all GATK walkers).</p>
                 <ul>
                     <#list extradocs as extradoc>
                         <li><a href="${extradoc.filename}">${extradoc.name}</a></li>