Now links to sub and superclass documentation, where possible.

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

@@ -29,6 +29,7 @@ import com.sun.javadoc.RootDoc;
 
 import java.io.*;
 import java.util.Map;
+import java.util.Set;
 
 /**
  *
@@ -51,5 +52,5 @@ public abstract class DocumentedGATKFeatureHandler {
     }
 
     public abstract String getTemplateName(ClassDoc doc) throws IOException;
-    public abstract void processOne(GATKDoclet.DocWorkUnit toProcess, Map<Class, GATKDoclet.DocWorkUnit> all);
+    public abstract void processOne(GATKDoclet.DocWorkUnit toProcess, Set<GATKDoclet.DocWorkUnit> all);
 }

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

@@ -102,8 +102,8 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
         return ResourceBundleExtractorDoclet.optionLength(option);
     }
 
-    public Map<Class, DocWorkUnit> workUnits() {
+    public Set<DocWorkUnit> workUnits() {
-        Map<Class, DocWorkUnit> m = new HashMap<Class, DocWorkUnit>();
+        TreeSet<DocWorkUnit> m = new TreeSet<DocWorkUnit>();
 
         for ( ClassDoc doc : rootDoc.classes() ) {
             System.out.printf("Considering %s%n", doc);
@@ -115,7 +115,7 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
                 DocWorkUnit unit = new DocWorkUnit(feature,
                         doc.name(), filename, feature.groupName(),
                         handler, doc, clazz );
-                m.put(clazz, unit);
+                m.add(unit);
             }
         }
 
@@ -137,12 +137,12 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
             // Specify how templates will see the data-model. This is an advanced topic...
             cfg.setObjectWrapper(new DefaultObjectWrapper());
 
-            Map<Class, DocWorkUnit> workUnitMap = workUnits();
+            Set<DocWorkUnit> myWorkUnits = workUnits();
-            for ( DocWorkUnit workUnit : workUnitMap.values() ) {
+            for ( DocWorkUnit workUnit : myWorkUnits ) {
-                processDocWorkUnit(cfg, workUnit, workUnitMap);
+                processDocWorkUnit(cfg, workUnit, myWorkUnits);
             }
 
-            processIndex(cfg, new ArrayList<DocWorkUnit>(workUnitMap.values()));
+            processIndex(cfg, new ArrayList<DocWorkUnit>(myWorkUnits));
         } catch ( FileNotFoundException e ) {
             throw new RuntimeException(e);
         } catch ( IOException e ) {
@@ -242,7 +242,14 @@ public class GATKDoclet extends ResourceBundleExtractorDoclet {
         return root;
     }
 
-    private void processDocWorkUnit(Configuration cfg, DocWorkUnit unit, Map<Class, DocWorkUnit> all)
+    public final static DocWorkUnit findWorkUnitForClass(Class c, Set<DocWorkUnit> all) {
+        for ( final DocWorkUnit unit : all )
+            if ( unit.clazz.equals(c) )
+                return unit;
+        return null;
+    }
+
+    private void processDocWorkUnit(Configuration cfg, DocWorkUnit unit, Set<DocWorkUnit> all)
             throws IOException {
         System.out.printf("Processing documentation for class %s%n", unit.classDoc);
 

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

@@ -41,6 +41,10 @@ import java.util.*;
  *
  */
 public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
+    GATKDoclet.DocWorkUnit toProcess;
+    ClassDoc classdoc;
+    Set<GATKDoclet.DocWorkUnit> all;
+
     @Override
     public boolean shouldBeProcessed(ClassDoc doc) {
         return true;
@@ -59,11 +63,23 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
     }
 
     @Override
-    public void processOne(GATKDoclet.DocWorkUnit toProcess, Map<Class, GATKDoclet.DocWorkUnit> all) {
+    public void processOne(GATKDoclet.DocWorkUnit toProcessArg, Set<GATKDoclet.DocWorkUnit> allArg) {
+        this.toProcess = toProcessArg;
+        this.all = allArg;
+        this.classdoc = toProcess.classDoc;
+
         System.out.printf("%s class %s%n", toProcess.group, toProcess.classDoc);
-        ClassDoc classdoc = toProcess.classDoc;
         Map<String, Object> root = new HashMap<String, Object>();
 
+        addHighLevelBindings(root);
+        addArgumentBindings(root);
+        addRelatedBindings(root);
+
+        //System.out.printf("Root is %s%n", root);
+        toProcess.setHandlerContent((String)root.get("summary"), root);
+    }
+
+    protected void addHighLevelBindings(Map<String, Object> root) {
         root.put("name", classdoc.name());
 
         // Extract overrides from the doc tags.
@@ -76,7 +92,9 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
         for(Tag tag: classdoc.tags()) {
             root.put(tag.name(), tag.text());
         }
+    }
 
+    protected void addArgumentBindings(Map<String, Object> root) {
         ParsingEngine parsingEngine = createStandardGATKParsingEngine();
 
         Map<String, List<Object>> args = new HashMap<String, List<Object>>();
@@ -102,10 +120,14 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
         } catch ( ClassNotFoundException e ) {
             throw new RuntimeException(e);
         }
+    }
 
+    protected void addRelatedBindings(Map<String, Object> root) {
         List<Map<String, Object>> extraDocsData = new ArrayList<Map<String, Object>>();
-        for ( Class extraDocClass : toProcess.annotation.extraDocs() ) {
+
-            final GATKDoclet.DocWorkUnit otherUnit = all.get(extraDocClass);
+        // add in all of the explicitly related items
+        for ( final Class extraDocClass : toProcess.annotation.extraDocs() ) {
+            final GATKDoclet.DocWorkUnit otherUnit = GATKDoclet.findWorkUnitForClass(extraDocClass, all);
             if ( otherUnit == null )
                 throw new ReviewedStingException("Requested extraDocs for class without any documentation: " + extraDocClass);
             extraDocsData.add(
@@ -114,10 +136,36 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
                         put("name", otherUnit.name);}});
 
         }
-        root.put("extradocs", extraDocsData);
 
-        //System.out.printf("Root is %s%n", root);
+        List<Map<String, Object>> hierarchyDocs = new ArrayList<Map<String, Object>>();
-        toProcess.setHandlerContent(summaryBuilder.toString(), root);
+        for (final GATKDoclet.DocWorkUnit 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);
+    }
+
+    private static final String classRelationship(Class me, Class other) {
+        if ( other.equals(me) )
+            // no circular references
+            return null;
+        else if ( other.isAssignableFrom(me) )
+            // toProcess is a superclass of other.clazz
+            return "superclass";
+        else if ( me.isAssignableFrom(other) )
+            // toProcess inherits from other.clazz
+            return "subclass";
+        else
+            return null;
+
     }
 
     protected ParsingEngine createStandardGATKParsingEngine() {

settings/helpTemplates/generic.template.html

@@ -24,19 +24,36 @@
     Details: ${arg.fulltext}<br>
 </#macro>     
    
+<#macro relatedByType name type>
+    <#list relatedDocs as relatedDoc>
+        <#if relatedDoc.relation == type>
+            <h3>${name}</h3>
+            <ul>
+            <#list relatedDocs as relatedDoc>
+                <#if relatedDoc.relation == type>
+                    <li><a href="${relatedDoc.filename}">${relatedDoc.name}</a> is a ${relatedDoc.relation}</li>
+                </#if>
+            </#list>
+            </ul>
+        <#break>        
+        </#if>
+    </#list>
+</#macro>
+   
+   
 <html>
 <head>
   <title>${name} documentation</title>
 </head>
 <body>
   <h1>${name}<h1>
-  <h2>Summary</h2>
+  <h2>Brief summary</h2>
   ${summary}
   <#if author??>
       <h2>Author</h2>
       ${author}
   </#if>
-  <h2>Description</h2>
+  <h2>Detailed description</h2>
   ${description}
   
   <#-- Create the argument summary -->
@@ -57,10 +74,10 @@
       </table>
   </#if>
 
-  <#-- Create references to related capabilities if appropriate -->
+  <#-- Create references to additional capabilities if appropriate -->
   <#if extradocs?size != 0> 
       <hr>
-      <h2>Related capabilities</h2>
+      <h2>Additional capabilities</h2>
       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.
@@ -70,6 +87,14 @@
       </#list>
       </ul>
   </#if>
+  
+  <#-- This class is related to other documented classes via sub/super relationships -->
+  <#if relatedDocs?size != 0> 
+    <h2>Related capabilities</h2>
+    <@relatedByType name="Superclasses" type="superclass"/>
+    <@relatedByType name="Subclasses" type="subclass"/>
+    <hr>
+  </#if>
     
   <#-- List all of the -->
   <#if arguments.all?size != 0>