Skip to content

feat(wdl-lint): support doc comments in MetaSections - #1185

Open
Serial-ATA wants to merge 1 commit into
stjude-rust-labs:mainfrom
Serial-ATA:meta-description
Open

feat(wdl-lint): support doc comments in MetaSections#1185
Serial-ATA wants to merge 1 commit into
stjude-rust-labs:mainfrom
Serial-ATA:meta-description

Conversation

@Serial-ATA

Copy link
Copy Markdown
Collaborator

part of #557

Before submitting this PR, please make sure:

For external contributors:

  • You have read the contributing guide in its entirety.
  • You have not used AI on any parts of this pull request.
  • You have added a few sentences describing the PR here.
  • Your code builds clean without any errors or warnings.

For all contributors:

  • You have added tests (when appropriate).
  • You have added an entry in the CHANGELOG (when appropriate).
  • You have updated the README or other documentation to account for these changes (when appropriate).
  • You have made a PR to the next branch in the sprocket.bio repository (when appropriate).

For PRs containing lint rule changes:

  • You have updated any and all effected entries within RULES.md.
  • You have added a test case in crates/wdl-lint/tests/lints that covers every
    possible diagnostic emitted for the rule within the file where the rule
    is implemented.

@Serial-ATA
Serial-ATA requested a review from a team as a code owner September 7, 2026 19:57
@Serial-ATA
Serial-ATA requested a review from a-frantz September 7, 2026 19:57
@Serial-ATA
Serial-ATA force-pushed the meta-description branch 2 times, most recently from 613d377 to 31a0eca Compare September 8, 2026 14:15
Comment thread crates/wdl-ast/src/lib.rs
pub fn doc_comments<N: TreeNode>(
preceding_trivia: impl IntoIterator<Item = N::Token>,
preceding_trivia: impl DoubleEndedIterator<Item = N::Token>,
allow_floating: bool,

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be consistent instead of decided ad hoc for each node type. I'm not sure which is preferable (always include "floating" doc comments or never), but I think we should pick one and apply that everywhere.

@Serial-ATA Serial-ATA Sep 9, 2026

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

floating comments are only allowed for preambles, which I think makes sense:

## This is a preamble

version 1.3

## This is a comment for `foo`
task foo {}

In that example, the comment on foo is clearly attached to the task definition. The preamble, though, is logically attached to the document and not the version statement, despite us internally treating the version statement as the documented node.

return;
}

// Only check struct definitions for WDL >=1.2

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

OOS for this PR, but should we start linting <1.2 structs for doc comment presence? They can't have meta sections within spec, but no reason they can't have doc comments.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sure, I'll make an issue after this is merged

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants