Summary

Deprecate the meta and parameter_meta sections in favor of inline documentation using a new comment delimiter (//) and markdown conventions.

Motivation

It is unusual for documentation to be part of a language's syntax itself. Most languages treat documentation as structured comments that are associated with the declarations they describe (e.g., Javadoc, rustdoc, Python docstrings). WDL's current approach has several drawbacks:

• Duplication: Parameter names must appear in both the declaration and the parameter_meta section, violating DRY principles.
• Disconnection: Documentation is physically separated from what it documents, making it harder to keep in sync.
• Maintenance burden: Renaming a parameter requires updating two locations.
• Parsing overhead: Engines must parse and validate structured metadata that is primarily intended for human consumption.

This would also address the confusion raised in #637 about parameter_meta documenting both inputs and outputs, since inline documentation would be directly associated with each declaration.

Proposed Approach

Introduce a line comment delimiter (//) that can be used anywhere in the document. When placed immediately before a declaration, it serves as documentation for that declaration. Documentation would use markdown conventions:

// # Wizard Spells // // A collection of tasks for casting magical spells. // // ## Author // // Merlin the Magnificent <merlin@camelot.gov> version 1.4 // A task that casts a spell. // // # Inputs // // - `spell_name`: The name of the spell to cast. // - `power_level`: The power level of the spell. Defaults to `10`. // // # Outputs // // - `incantation`: The resulting incantation. task cast_spell {  input { // The name of the spell to cast. String spell_name // The power level of the spell. Defaults to `10`. Int power_level = 10 } command <<<  echo "Casting ~{spell_name} at power level ~{power_level}!"  >>>  output { // The resulting incantation. String incantation = read_string(stdout()) } }

Structured metadata could be expressed through markdown conventions (e.g., headings, bulleted lists) rather than special syntax.

If there is strong opposition to introducing a new comment delimiter, # could work as well. However, I find that block comments look rather strange with that syntax, so // is my suggestion.

Related

• documenting outputs in **parameter**_meta isn't clear #637