Support parameter_meta section

[multimeric]

Ideally each input in the generated task could have some sort of annotation in the parameter_meta section, for example the description of that input.

This is so that the following snippet could be generated with Python:

task runtime_meta {
  input {
    String memory_mb
    String sample_id
    String param
    String sample_id
  }
  command {
    java -Xmx${memory_mb}M -jar task.jar -id ${sample_id} -param ${param} -out ${sample_id}.out
  }
  output {
    File results = "${sample_id}.out"
  }
  runtime {
    docker: "broadinstitute/baseimg"
  }
  parameter_meta {
    memory_mb: "Amount of memory to allocate to the JVM"
    param: "Some arbitrary parameter"
    sample_id: "The ID of the sample in format foo_bar_baz"
  }
  meta {
    author: "Joe Somebody"
    email: "joe@company.org"
  }
}

[illusional]

I think this a great idea and would be a worthy addition to the project. There’s two ways I can see it being done:

1. Adding a meta tag to a TaskInput, and generating the parameter_meta field from that.

2. Adding a ParameterMeta object that’s a k-v field you can add your own fields to. I think this is purer and closer to what this project is really trying to represent (not a workflow builder / way to abstract concepts [though it doesn’t strictly succeed at that], a layer between wdl and python).

I’m pretty happy to build (2) soon, or very happy to take a contribution.

And all of this too for the meta field. Though we could allow for arbitrary k-v and be opinionated about some fields (like author / email / etc).

[illusional]

Also just following this discussion (openwdl/wdl#359 (comment)), we could add specific options for recognised meta options.

[multimeric]

I think in either case it should allow arbitrary key-value pairs below the root-level keys, since that's what's in the spec.

As you say, the question of whether you should have a new top-level key for this, or whether it should be attached to a TaskInput is more of an API design choice than anything else. If it were me, I'd opt for abstraction and API simplicity, and bundle Input, TaskInput, and the parameter_meta dictionary into one big Input class. However by separating all these concepts, I can see that you've already opted to make a more literal WDL building API with less abstraction. Considering this, I suppose the most consistent thing to do would be to add parameter_meta as a root-level key to the Task (option 2), and accept the fact that users can add keys that don't correspond to the inputs, which may not make sense.