Configuration for where outputs should be documented

[a-frantz]

Continuation/migration of stjude-rust-labs/sprocket#3

The gist: The community is divided here. Some of us are of the opinion that outputs should be documented in the meta section and some of us feel they should be documented in the parameter_meta section. IMO we need to support both. What exactly that looks like is a bit in the air.

In the absence of any public outrage, this repo is going to take the stance that the default behavior should be output documentation belongs in the meta section. But we should provide some simple and straightforward way to change that behavior so that output docs will be looked for in the parmater_meta section.

[peterhuene]

Ideally I hope we can steer the community towards using comments for this purpose, as that's what every other language out there does; it keeps the documentation close to the thing it's documenting.

We could certainly support both and have our documentation generation tool respect comments in lieu of documentation-related values inparameter_meta and meta (and error if both are present or perhaps merge them together?).

[a-frantz]

I'm worried that what you're suggesting is an uphill battle. I don't disagree with any of your points, but I also think the path of least resistance is going to be continuing to use parameter_meta and the adoption of an output_meta (tangential link: openwdl/wdl#637). Getting an output_meta (or renaming parameter_meta to declaration_meta) seems like a large enough challenge.

Certainly open to having my mind changed, but I wouldn't advocate for formalizing any kind of doc comment (and by extension I'm opposed to integrating doc comments into sprocket functionality).

To be explicit, I think something in the language specification should change. I do not like the specifications recommendation to document outputs within the parameter_meta. I see the https://github.com/stjudecloud/workflows approach as a bandaid. (For context, our workflows convention is to have an output key in the meta section that functions more-or-less like a nested parameter_meta).

I'm interested to hear more opinions on this. Maybe we should create a Feedback Gathering discussion thread for this and spread the link around.

From where I'm standing, I see the future of WDL potentially going a few different ways.

1. the status quo continues.
   • From what I've seen the community at large seems ambivalent about this issue. We could be deemed old folks yelling at the clouds here.
2. new output_meta
   • Ideally with this comes a restriction of input only in parameter_meta
3. renaming parameter_meta to declaration_meta (or something similar)
   • this would be "mixing" input and output documentation and I'm not a fan, but it would be an improvement IMO.
4. doc comments
   • my big issue with this is that it puts the meta and parameter_meta sections into a weird spot. Why is some documentation relegated to trivia and some to formalized code? If the WDL world goes this route, I'd like to go all the way and abandon the current meta sections in favor of putting everything in doc comments.

[peterhuene]

my big issue with this is that it puts the meta and parameter_meta sections into a weird spot. Why is some documentation relegated to trivia and some to formalized code? If the WDL world goes this route, I'd like to go all the way and abandon the current meta sections in favor of putting everything in doc comments.

Considering 1.2 just added meta and parameter_meta to structs, I don't think they're going anywhere any time soon; I realize my suggestion is mostly a pipe dream, but I do wonder how much we can steer our documentation tooling in a direction that both respects the spec and also is flexible enough to offer an alternative to those that want one (i.e. driven off of the meta sections primarily, but if you'd like to use doc comments instead, who are we to judge?).

That said, if it seems like the WDL community at-large doesn't care about the issue, then I think what you've proposed above makes sense: default to meta for outputs, make it configurable to switch to parameter_meta, and advocate in the WDL spec for a dedicated output_meta section.

[a-frantz]

but I do wonder how much we can steer our documentation tooling in a direction that both respects the spec and also is flexible enough to offer an alternative to those that want one (i.e. driven off of the meta sections primarily, but if you'd like to use doc comments instead, who are we to judge?).

(clarification: from here on out assume every instance of "doc comments" is followed by "(except preamble comments)". I like preamble comments, and I think we're all on board with them. I'm here to oppose adopting new doc comments)

I'm not convinced that we should have any doc comments. I was wishy-washy on the idea up until this morning. The addition of meta sections for struct definitions eliminates any use case I can think of for doc comments. It just strikes me as a needless complication, when there's already infrastructure for all documentation needs. (Granted, I can't argue in good faith that the existing infrastructure is flawless. I have complaints and I can't say I'm not tempted by a full-fledged doc comment approach. But that would be a complete 180 for the language that I don't see materializing.)

What's a documentation need that can't be addressed with the existing meta sections (specifically in versions >=1.2) and preamble comments? I think new doc comment conventions would be reinventing the wheel. We should stick with what's baked into the language (plus preamble comments). It covers everything we need.