From 91bfecea67b78f7e459a250a7844c6344154367f Mon Sep 17 00:00:00 2001
From: John Chilton <jmchilton@gmail.com>
Date: Fri, 7 Oct 2016 15:56:02 -0400
Subject: [PATCH] Add documentation on optional ``multiple="true"`` data
 parameters.

Thanks to detailed biostar question from @lindenb (sorry these parameters are so counter-intuitive - I don't have an excuse other than a need to preserve backward compatibility).

Rebased with indention requested by @nsoranzo and fixes for the test case tool.
---
 lib/galaxy/tools/xsd/galaxy.xsd               | 27 +++++++++++++++++++
 test/functional/tools/multi_data_optional.xml | 27 +++++++++++++++++++
 test/functional/tools/samples_tool_conf.xml   |  1 +
 3 files changed, 55 insertions(+)
 create mode 100644 test/functional/tools/multi_data_optional.xml

diff --git a/lib/galaxy/tools/xsd/galaxy.xsd b/lib/galaxy/tools/xsd/galaxy.xsd
index 8d0cecc92c1..978fc769716 100644
--- a/lib/galaxy/tools/xsd/galaxy.xsd
+++ b/lib/galaxy/tools/xsd/galaxy.xsd
@@ -1990,6 +1990,33 @@ multiple formats.
        help="The set of aligned reads." />
 ```
 
+Perhaps counter-intuitively, a ``multiple="true"`` data parameter requires at least one
+data input. If ``optional="true"`` is specified, this condition is relaxed and the user
+is allowed to select 0 datasets. Unfortunately, if 0 datasets are selected the resulting
+value for the parameter during Cheetah templating (such as in a ``command`` block) will
+effectively be a list with one ``None``-like entity in it.
+
+The following idiom can be used to iterate over such a list and build a hypothetical ``-B``
+parameter for each file - the ``if`` block is used to handle the case where a ``None``-like
+entity appears in the list because no files were selected: 
+
+```
+#for $input in $input1
+    #if $input
+        -B "$input"
+    #end if
+#end for
+```
+
+Some example tools using ``multiple="true"`` data parameters include:
+
+- [multi_data_param.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_data_param.xml)
+- [multi_data_optional.xml](https://github.com/galaxyproject/galaxy/blob/dev/test/functional/tools/multi_data_optional.xml)
+
+Additionally, a detailed discussion of handling multiple homogenous files can be found in the
+the [Planemo Documentation](http://planemo.readthedocs.io/en/latest/writing_advanced.html#consuming-collections)
+on this topic.
+
 $attribute_list:format,multiple
 
 #### ``select``
diff --git a/test/functional/tools/multi_data_optional.xml b/test/functional/tools/multi_data_optional.xml
new file mode 100644
index 00000000000..5f914259f8a
--- /dev/null
+++ b/test/functional/tools/multi_data_optional.xml
@@ -0,0 +1,27 @@
+<tool id="multi_data_optional" name="multi_data_optional" version="0.1.0">
+  <command>
+    touch $out1;
+    #for $input in $input1
+    #if $input
+    cat $input >> $out1;
+    #end if
+    #end for
+  </command>
+  <inputs>
+    <param name="input1" type="data" format="txt" multiple="true" label="Data 1" optional="true" />
+  </inputs>
+  <outputs>
+    <data format="txt" name="out1" />
+  </outputs>
+  <tests>
+    <test>
+      <param name="input1" value="simple_line.txt,simple_line_alternative.txt" />
+      <output name="out1">
+        <assert_contents>
+          <has_line line="This is a line of text." />
+          <has_line line="This is a different line of text." />
+        </assert_contents>
+      </output>
+    </test>
+  </tests>
+</tool>
diff --git a/test/functional/tools/samples_tool_conf.xml b/test/functional/tools/samples_tool_conf.xml
index d57356e25d9..6286cbcb9c0 100644
--- a/test/functional/tools/samples_tool_conf.xml
+++ b/test/functional/tools/samples_tool_conf.xml
@@ -57,6 +57,7 @@
   <tool file="implicit_default_conds.xml" />
   <tool file="multi_data_param.xml" />
   <tool file="multi_data_repeat.xml" />
+  <tool file="multi_data_optional.xml" />
   <tool file="paths_as_file.xml" />
   <tool file="column_param.xml" />
   <tool file="column_multi_param.xml" />