Multi-line strings in meta, parameter_meta

[cjllanwarne]

If we want to put rich information in there, we should allow >1 line of text. We could maybe re-use the triple-angle brackets style, eg:

workflow foo {
  meta {
    description: <<<
      # Foo.wdl
      ---
      This could be a looo...
      ...
      ...
      ...oong Markdown description of the workflow, for example
    >>>
  }
}

[patmagee]

I like this as its sticking to the convention used in the command block. The only problem I can see is that the value of the property in meta and parameter meta can be valid json now (i believe), so users might also look to nest this type of multi-line string directly in a json object.

I think thats okay if we define what the <<< >>> actually means. If we state that this must be interpreted as a single string by any implementation, users would be able to embed this within any of the json objects they are writing.

I would actually go one step farther here and state that <<< >>> should just be interpreted as a multi-line String literal. This would make it useful in other places, not just in the meta and parameter_meta section. IE:

task foo {
   String myString = <<<
      Foo
      Baz
      BIiz
>>>
}

[geoffjentry]

meta-comment (pardon the pun). If we're going to start building out the meta sections, is it worth rethinking them altogether, from the perspective of "are these the right thing?". I don't have any particular beef with them (no, that's runtime!) but I'd hate to just be adding on a lot of patches to something which is fundamentally a bad abstraction (not saying it is, not saying it isn't)

[ambrosejcarr]

We in Mint need some kind of abstraction that allows us to add documentation to WDL files. We're currently using meta and parameter_meta to do this, as there doesn't appear to be a better alternative.

Without multi-line strings, they make our files pretty hideous, so big 👍 on this issue.

[aednichols]

👍 to the idea of adding the multi-line string literal and thereby gaining the ability to use it in meta

Longer term, it seems like we could go in a Javadoc-like direction where documentation is in comments adjacent to the thing it describes.

This would let us generate documentation from the workflow with a documenting tool, but would exclude the documentation strings from appearing anywhere at runtime. (Engine-specific hints would still live in *meta.)

[SHuang-Broad]

👍

[rhpvorderman]

:+1:

[jdidion]

Fixed by #522