search

common-workflow-language / user_guide

The CWL v1.0 - v1.2 user guide
http://www.commonwl.org/user_guide/
Other
42 stars 67 forks source link

In "Inputs" > "Array Inputs", there should be more emphasis on where `inputBinding` appears #400

Open zoe-translates opened 1 year ago

zoe-translates commented 1 year ago

https://github.com/common-workflow-language/user_guide/blob/499d120c2d16bd41e358ec03a8ed95832a18bff1/src/topics/inputs.md?plain=1#L178-L180

This bit wasn't very clear, because it didn't clarify where "as above" specifically referred to, and what sort of "different behavior[s]" were expected.

It's clear that the text meant to direct the user's attention to filesB in the array-inputs.cwl file, where comparison with the other two inputs should lead to an observation about inputBinding on array vs. array elements.

But for one thing, this wasn't made clear. The user should've been given direct instruction about where to look. The code block was a bit far up, and its content a bit complicated with multiple levels of nesting.

In addition, it was difficult to reach a conclusion about "the different effect of inputBinding on array vs. array elements" just by observation alone. filesB differs from the other two inputs not just by the presence of inputBinding for elements (even this may not be clear to a new user). So it would be useful to explain in words the difference of behaviors with or without inputBinding on elements.

mr-c commented 1 year ago

Thank you @zoe-translates ; I agree with your comments