Filter non-CLPs from inclusion in tab completion. (#164)

Author: cmnbroad

src/main/java/org/broadinstitute/barclay/help/BashTabCompletionDocWorkUnitHandler.java

@@ -0,0 +1,26 @@
+package org.broadinstitute.barclay.help;
+
+/**
+ * Work unit handler for tab completion work units.
+ */
+public class BashTabCompletionDocWorkUnitHandler extends DefaultDocWorkUnitHandler {
+
+    /**
+     * @param doclet for this run. May not be null.
+     */
+    public BashTabCompletionDocWorkUnitHandler(final HelpDoclet doclet) {
+        super(doclet);
+    }
+
+    /**
+     * Add bindings describing related capabilities to currentWorkUnit. The tab completion doclet filters
+     * out any work unit that represents a class that doesn't have
+     * {@link org.broadinstitute.barclay.argparser.CommandLineProgramProperties}. Since doing so may filter
+     * out classes that are referenced by the extraDocs attribute in classes that ARE
+     * {@link org.broadinstitute.barclay.argparser.CommandLineProgramProperties}, we need to suppress
+     * resolution of extraDocs for tab completion work units by overriding this method to do nothing.
+     */
+    @Override
+    protected void addExtraDocsBindings(final DocWorkUnit currentWorkUnit) { }
+
+}

src/main/java/org/broadinstitute/barclay/help/BashTabCompletionDoclet.java

@@ -1,9 +1,11 @@
 package org.broadinstitute.barclay.help;
 
+import com.sun.javadoc.ClassDoc;
 import com.sun.javadoc.RootDoc;
 import freemarker.template.Configuration;
 import freemarker.template.Template;
 import freemarker.template.TemplateException;
+import org.broadinstitute.barclay.argparser.CommandLineProgramProperties;
 
 import java.io.*;
 import java.util.*;
@@ -390,6 +392,37 @@ else if (option[0].equals(CALLER_SCRIPT_POSTFIX_ARG_MAX_OCCURRENCES)) {
         return hasParsedOption;
     }
 
+    /**
+     * Filter out features that are not command line programs by selecting only classes with
+     * {@link CommandLineProgramProperties}.
+     * @param documentedFeature feature that is being considered for inclusion in the docs
+     * @param classDoc for the class that is being considered for inclusion in the docs
+     * @param clazz class that is being considered for inclusion in the docs
+     * @return
+     */
+    @Override
+    public boolean includeInDocs(final DocumentedFeature documentedFeature, final ClassDoc classDoc, final Class<?> clazz) {
+        return super.includeInDocs(documentedFeature, classDoc, clazz) &&
+                clazz.getAnnotation(CommandLineProgramProperties.class) != null;
+    }
+
+    /**
+     * Create a work unit and handler capable of handling the feature specified by the input arguments.
+     * Returns null if no appropriate handler is found or doc shouldn't be documented at all.
+     */
+    @Override
+    protected DocWorkUnit createWorkUnit(
+            final DocumentedFeature documentedFeature,
+            final ClassDoc classDoc,
+            final Class<?> clazz)
+    {
+        return new DocWorkUnit(
+                new BashTabCompletionDocWorkUnitHandler(this),
+                documentedFeature,
+                classDoc,
+                clazz);
+    }
+
     @Override
     protected void processWorkUnitTemplate(
             final Configuration cfg,

src/main/java/org/broadinstitute/barclay/help/HelpDoclet.java

@@ -296,8 +296,8 @@ private Set<DocWorkUnit> computeWorkUnits() {
             final DocumentedFeature documentedFeature = getDocumentedFeatureForClass(clazz);
 
             if (documentedFeature != null) {
-                if (documentedFeature.enable()) {
-                    DocWorkUnit workUnit = createWorkUnit(
+                if (documentedFeature.enable() && includeInDocs(documentedFeature, classDoc, clazz)) {
+                        DocWorkUnit workUnit = createWorkUnit(
                             documentedFeature,
                             classDoc,
                             clazz);

src/test/resources/org/broadinstitute/barclay/help/expected/BashTabCompletionDoclet/bashTabCompletionDocletTestLaunch-completion.sh

@@ -11,13 +11,13 @@
 CALLER_SCRIPT_NAME="bashTabCompletionDocletTestLaunch"
 
 # A description of these variables is below in the main completion function (_masterCompletionFunction)
-CS_PREFIX_OPTIONS_ALL_LEGAL_ARGUMENTS=(--pre-help --pre-info --pre-inputFile TestExtraDocs TestArgumentContainer )
-CS_PREFIX_OPTIONS_NORMAL_COMPLETION_ARGUMENTS=(--pre-help --pre-info --pre-inputFile TestExtraDocs TestArgumentContainer )
-CS_PREFIX_OPTIONS_ALL_ARGUMENT_VALUE_TYPES=("null" "null" "File" "null" "null" )
+CS_PREFIX_OPTIONS_ALL_LEGAL_ARGUMENTS=(--pre-help --pre-info --pre-inputFile TestArgumentContainer )
+CS_PREFIX_OPTIONS_NORMAL_COMPLETION_ARGUMENTS=(--pre-help --pre-info --pre-inputFile TestArgumentContainer )
+CS_PREFIX_OPTIONS_ALL_ARGUMENT_VALUE_TYPES=("null" "null" "File" "null" )
 CS_PREFIX_OPTIONS_MUTUALLY_EXCLUSIVE_ARGS=("--pre-help;pre-info,pre-inputFile" "--pre-info;pre-help,pre-inputFile")
 CS_PREFIX_OPTIONS_SYNONYMOUS_ARGS=("--pre-help;-prh" "--pre-inputFile;-prif")
-CS_PREFIX_OPTIONS_MIN_OCCURRENCES=(0 0 1 0 0 )
-CS_PREFIX_OPTIONS_MAX_OCCURRENCES=(1 1 1 1 1 )
+CS_PREFIX_OPTIONS_MIN_OCCURRENCES=(0 0 1 0 )
+CS_PREFIX_OPTIONS_MAX_OCCURRENCES=(1 1 1 1 )
 
 CS_POSTFIX_OPTIONS_ALL_LEGAL_ARGUMENTS=(--post-help --post-info --post-inputFile)
 CS_POSTFIX_OPTIONS_NORMAL_COMPLETION_ARGUMENTS=(--post-help --post-info --post-inputFile)
@@ -31,7 +31,7 @@ CS_POSTFIX_OPTIONS_MAX_OCCURRENCES=(1 1 1)
 HAS_POSTFIX_OPTIONS="true"
 
 # All the tool names we are able to complete:
-ALL_TOOLS=(TestExtraDocs TestArgumentContainer )
+ALL_TOOLS=(TestArgumentContainer )
 
 ####################################################################################################
 
@@ -422,20 +422,6 @@ _bashTabCompletionDocletTestLaunch_masterCompletionFunction()
         # Set our reply as a list of the possible tool matches:
         COMPREPLY=( $(compgen -W '${possibleToolMatches[@]}' -- $cur) )
 
-    elif [[ ${toolName} == "TestExtraDocs" ]] ; then
-
-        # Set up the completion information for this tool:
-        DEPENDENT_ARGUMENTS=()
-        NORMAL_COMPLETION_ARGUMENTS=(--extraDocsArgument )
-        MUTUALLY_EXCLUSIVE_ARGS=()
-        SYNONYMOUS_ARGS=("--extraDocsArgument;-extDocArg" )
-        MIN_OCCURRENCES=(0 )
-        MAX_OCCURRENCES=(2147483647 )
-        ALL_LEGAL_ARGUMENTS=(--extraDocsArgument )
-        ALL_ARGUMENT_VALUE_TYPES=("String" )
-
-        # Complete the arguments for this tool:
-        _bashTabCompletionDocletTestLaunch_handleArgs
     elif [[ ${toolName} == "TestArgumentContainer" ]] ; then
 
         # Set up the completion information for this tool:

src/test/resources/org/broadinstitute/barclay/help/expected/BashTabCompletionDoclet/bashTabCompletionDocletTestLaunchWithDefaults-completion.sh

@@ -11,13 +11,13 @@
 CALLER_SCRIPT_NAME="bashTabCompletionDocletTestLaunchWithDefaults"
 
 # A description of these variables is below in the main completion function (_masterCompletionFunction)
-CS_PREFIX_OPTIONS_ALL_LEGAL_ARGUMENTS=( TestExtraDocs TestArgumentContainer )
-CS_PREFIX_OPTIONS_NORMAL_COMPLETION_ARGUMENTS=( TestExtraDocs TestArgumentContainer )
-CS_PREFIX_OPTIONS_ALL_ARGUMENT_VALUE_TYPES=( "null" "null" )
+CS_PREFIX_OPTIONS_ALL_LEGAL_ARGUMENTS=( TestArgumentContainer )
+CS_PREFIX_OPTIONS_NORMAL_COMPLETION_ARGUMENTS=( TestArgumentContainer )
+CS_PREFIX_OPTIONS_ALL_ARGUMENT_VALUE_TYPES=( "null" )
 CS_PREFIX_OPTIONS_MUTUALLY_EXCLUSIVE_ARGS=()
 CS_PREFIX_OPTIONS_SYNONYMOUS_ARGS=()
-CS_PREFIX_OPTIONS_MIN_OCCURRENCES=( 0 0 )
-CS_PREFIX_OPTIONS_MAX_OCCURRENCES=( 1 1 )
+CS_PREFIX_OPTIONS_MIN_OCCURRENCES=( 0 )
+CS_PREFIX_OPTIONS_MAX_OCCURRENCES=( 1 )
 
 CS_POSTFIX_OPTIONS_ALL_LEGAL_ARGUMENTS=()
 CS_POSTFIX_OPTIONS_NORMAL_COMPLETION_ARGUMENTS=()
@@ -31,7 +31,7 @@ CS_POSTFIX_OPTIONS_MAX_OCCURRENCES=()
 HAS_POSTFIX_OPTIONS="false"
 
 # All the tool names we are able to complete:
-ALL_TOOLS=(TestExtraDocs TestArgumentContainer )
+ALL_TOOLS=(TestArgumentContainer )
 
 ####################################################################################################
 
@@ -422,20 +422,6 @@ _bashTabCompletionDocletTestLaunchWithDefaults_masterCompletionFunction()
         # Set our reply as a list of the possible tool matches:
         COMPREPLY=( $(compgen -W '${possibleToolMatches[@]}' -- $cur) )
 
-    elif [[ ${toolName} == "TestExtraDocs" ]] ; then
-
-        # Set up the completion information for this tool:
-        DEPENDENT_ARGUMENTS=()
-        NORMAL_COMPLETION_ARGUMENTS=(--extraDocsArgument )
-        MUTUALLY_EXCLUSIVE_ARGS=()
-        SYNONYMOUS_ARGS=("--extraDocsArgument;-extDocArg" )
-        MIN_OCCURRENCES=(0 )
-        MAX_OCCURRENCES=(2147483647 )
-        ALL_LEGAL_ARGUMENTS=(--extraDocsArgument )
-        ALL_ARGUMENT_VALUE_TYPES=("String" )
-
-        # Complete the arguments for this tool:
-        _bashTabCompletionDocletTestLaunchWithDefaults_handleArgs
     elif [[ ${toolName} == "TestArgumentContainer" ]] ; then
 
         # Set up the completion information for this tool: