Better documentation for default value fields

-- DocString function for types that create default outputs "stdout"
-- RodBinding now creates a makeUnbound default value automatically for you if your RodBinding isn't required
-- Removed warning about sparse help from TextFormattingUtils

public/java/src/org/broadinstitute/sting/commandline/ArgumentSource.java

@@ -175,6 +175,10 @@ public class ArgumentSource {
         return typeDescriptor.createsTypeDefault(this);
     }
 
+    public String typeDefaultDocString() {
+        return typeDescriptor.typeDefaultDocString(this);
+    }
+
     /**
      * Generates a default for the given type.
      * @param parsingEngine the parsing engine used to validate this argument type descriptor.

public/java/src/org/broadinstitute/sting/commandline/ArgumentTypeDescriptor.java

@@ -83,6 +83,17 @@ public abstract class ArgumentTypeDescriptor {
      */
     public boolean createsTypeDefault(ArgumentSource source) { return false; }
 
+    /**
+     * Returns a documentation-friendly value for the default of a type descriptor.
+     * Must be overridden if createsTypeDefault return true.  cannot be called otherwise
+     * @param source Source of the command-line argument.
+     * @return Friendly string of the default value, for documentation.  If doesn't create a default, throws
+     * and UnsupportedOperationException
+     */
+    public String typeDefaultDocString(ArgumentSource source) {
+        throw new UnsupportedOperationException();
+    }
+
     /**
      * Generates a default for the given type.
      * @param parsingEngine the parsing engine used to validate this argument type descriptor.
@@ -308,6 +319,19 @@ class RodBindingArgumentTypeDescriptor extends ArgumentTypeDescriptor {
         return RodBinding.class.isAssignableFrom(type);
     }
 
+    @Override
+    public boolean createsTypeDefault(ArgumentSource source) { return ! source.isRequired(); }
+
+    @Override
+    public Object createTypeDefault(ParsingEngine parsingEngine, ArgumentSource source, Class<?> type) {
+        return RodBinding.makeUnbound((Class<? extends Feature>)type);
+    }
+
+    @Override
+    public String typeDefaultDocString(ArgumentSource source) {
+        return "none";
+    }
+
     @Override
     public Object parse(ParsingEngine parsingEngine, ArgumentSource source, Type type, ArgumentMatches matches) {
         ArgumentDefinition defaultDefinition = createDefaultArgumentDefinition(source);
@@ -639,6 +663,10 @@ class MultiplexArgumentTypeDescriptor extends ArgumentTypeDescriptor {
         return multiplexedMapping;
     }
 
+    @Override
+    public String typeDefaultDocString(ArgumentSource source) {
+        return "None";
+    }
 
     @Override
     public Object parse(ParsingEngine parsingEngine, ArgumentSource source, Type type, ArgumentMatches matches) {

public/java/src/org/broadinstitute/sting/gatk/io/stubs/OutputStreamArgumentTypeDescriptor.java

@@ -69,6 +69,11 @@ public class OutputStreamArgumentTypeDescriptor extends ArgumentTypeDescriptor {
         return source.isRequired();
     }
 
+    @Override
+    public String typeDefaultDocString(ArgumentSource source) {
+        return "stdout";
+    }
+
     @Override
     public Object createTypeDefault(ParsingEngine parsingEngine,ArgumentSource source,Class type) {
         if(!source.isRequired())

public/java/src/org/broadinstitute/sting/gatk/io/stubs/SAMFileReaderArgumentTypeDescriptor.java

@@ -53,7 +53,6 @@ public class SAMFileReaderArgumentTypeDescriptor extends ArgumentTypeDescriptor
         this.engine = engine;
     }
 
-
     @Override
     public boolean supports( Class type ) {
         return SAMFileReader.class.isAssignableFrom(type);

public/java/src/org/broadinstitute/sting/gatk/io/stubs/SAMFileWriterArgumentTypeDescriptor.java

@@ -93,6 +93,11 @@ public class SAMFileWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor
         return source.isRequired();
     }
 
+    @Override
+    public String typeDefaultDocString(ArgumentSource source) {
+        return "stdout";
+    }
+
     @Override
     public Object createTypeDefault(ParsingEngine parsingEngine,ArgumentSource source,Class<?> type) {
         if(!source.isRequired())

public/java/src/org/broadinstitute/sting/gatk/io/stubs/VCFWriterArgumentTypeDescriptor.java

@@ -108,6 +108,11 @@ public class VCFWriterArgumentTypeDescriptor extends ArgumentTypeDescriptor {
         return source.isRequired();
     }
 
+    @Override
+    public String typeDefaultDocString(ArgumentSource source) {
+        return "stdout";
+    }
+
     @Override
     public Object createTypeDefault(ParsingEngine parsingEngine,ArgumentSource source,Class<?> type) {
         if(!source.isRequired())

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

@@ -93,7 +93,7 @@ public class GATKDoclet {
         TreeSet<GATKDocWorkUnit> m = new TreeSet<GATKDocWorkUnit>();
 
         for ( ClassDoc doc : rootDoc.classes() ) {
-            logger.debug("Considering " + doc);
+            //logger.debug("Considering " + doc);
             Class clazz = getClassForClassDoc(doc);
 
             if ( clazz != null && clazz.getName().equals("org.broadinstitute.sting.gatk.walkers.annotator.AlleleBalance"))
@@ -102,7 +102,7 @@ public class GATKDoclet {
             DocumentedGATKFeature feature = getFeatureForClassDoc(doc);
             DocumentedGATKFeatureHandler handler = createHandler(doc, feature);
             if ( handler != null && handler.includeInDocs(doc) ) {
-                logger.info("Going to generate 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(),

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

@@ -129,6 +129,16 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
                     // get the value of the field
                     if ( instance != null ) {
                         Object value = getFieldValue(toProcess.clazz, instance, fieldDoc.name());
+
+                        if ( value == null && argumentSource.createsTypeDefault() ) {
+                            // handle the case where there's an implicit default
+                            try {
+                                value = argumentSource.typeDefaultDocString();
+                            } catch (ReviewedStingException e) {
+                                ; // failed to create type default, don't worry about it
+                            }
+                        }
+
                         if ( value != null )
                             argBindings.put("defaultValue", prettyPrintValueString(value));
                     }
@@ -197,8 +207,11 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
                 return Arrays.toString((Object[])value);
             else
                 throw new RuntimeException("Unexpected array type in prettyPrintValue.  Value was " + value + " type is " + type);
-        } else
+        } else if ( RodBinding.class.isAssignableFrom(value.getClass() ) )
-            return value.toString();
+            // annoying special case to handle the UnBound() constructor
+            return "none";
+
+        return value.toString();
     }
 
     private Object makeInstanceIfPossible(Class c) {
@@ -220,10 +233,10 @@ public class GenericDocumentationHandler extends DocumentedGATKFeatureHandler {
         // this last one is super dangerous, but some of these methods catch ClassNotFoundExceptions
         // and rethrow then as RuntimeExceptions
         catch (RuntimeException e) {}
-        finally {
+//        finally {
-            if ( instance == null )
+//            if ( instance == null )
-                logger.warn(String.format("Unable to create instance of class %s => %s", c, instance));
+//                logger.warn(String.format("Unable to create instance of class %s => %s", c, instance));
-        }
+//        }
 
         return instance;
     }

public/java/src/org/broadinstitute/sting/utils/text/TextFormattingUtils.java

@@ -104,7 +104,7 @@ public class TextFormattingUtils {
             bundle = ResourceBundle.getBundle(bundleName);
         }
         catch(MissingResourceException ex) {
-            logger.warn("Unable to load help text.  Help output will be sparse.");
+            //logger.warn("Unable to load help text.  Help output will be sparse.");
             // Generate an empty resource bundle.
             try {
                 bundle = new PropertyResourceBundle(new StringReader(""));