Repository: stjude-rust-labs/wdl
Pull request #373: docs: DEFINITIONS.md for WDL concepts
Author: login: Gyan-max
Created: 2025-03-28T13:38:13Z | Merged: 2025-03-28T18:56:44Z

# Add DEFINITIONS.md for WDL concept documentation

This commit adds a dedicated DEFINITIONS.md file to document key WDL concepts such as lint directives and preamble comments. These definitions were previously embedded in individual rule explanations (particularly in the PreambleFormatting rule).

The following changes were made:

- Created wdl-lint/DEFINITIONS.md with comprehensive definitions
- Updated wdl-lint/src/lib.rs to include DEFINITIONS.md in docs.rs
- Refactored explanation() text in three rules to reference DEFINITIONS.md

Closes stjude-rust-labs/sprocket#312

<!-- START SECTION: any other pull request -->

This PR addresses issue stjude-rust-labs/sprocket#312 by creating a dedicated centralized location for WDL concept definitions, improving maintainability while ensuring comprehensive documentation remains available to users.

Before submitting this PR, please make sure:

- [x] You have added a few sentences describing the PR here.
- [x] You have added yourself or the appropriate individual as the assignee.
- [x] You have added at least one relevant code reviewer to the PR.
- [x] Your code builds clean without any errors or warnings.
- [x] You have added tests (when appropriate).
- [x] You have updated the README or other documentation to account for these
      changes (when appropriate).
- [x] You have added an entry to the relevant `CHANGELOG.md` (see
      ["keep a changelog"] for more information).
- [x] Your commit messages follow the [conventional commit] style.
- [x] Your PR title follows the [conventional commit] style.

<!-- END SECTION -->

[conventional commit]: https://www.conventionalcommits.org/en/v1.0.0/#summary
["keep a changelog"]: https://keepachangelog.com/en/1.1.0/


Diff:
diff --git a/wdl-lint/CHANGELOG.md b/wdl-lint/CHANGELOG.md
index 41485507c..3571096c4 100644
--- a/wdl-lint/CHANGELOG.md
+++ b/wdl-lint/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Added suggestion for similar rule names when encountering unknown lint rules ([#334](https://github.com/stjude-rust-labs/wdl/pull/334)).
 * Added `DisallowedDeclarationName` rule ([#343](https://github.com/stjude-rust-labs/wdl/pull/343)).
+* Added `DEFINITIONS.md` file with centralized documentation for WDL concepts ([#195](https://github.com/stjude-rust-labs/wdl/pull/195)).
 * Added `Rule::related_rules()` for linking related lint rules ([#371](https://github.com/stjude-rust-labs/wdl/pull/371)).
 
 ### Changed
diff --git a/wdl-lint/DEFINITIONS.md b/wdl-lint/DEFINITIONS.md
new file mode 100644
index 000000000..51ea60e8c
--- /dev/null
+++ b/wdl-lint/DEFINITIONS.md
@@ -0,0 +1,31 @@
+# Definitions
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document.
+
+For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+### Preamble Comments
+
+Preamble comments are special comments at the start of a WDL file that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of a workflow. Preamble comments can be formatted as Markdown text.
+
+For example:
+
+```wdl
+## # FlagFilter
+##
+## A struct to represent the filtering flags used in various `samtools` commands.
+```
diff --git a/wdl-lint/src/lib.rs b/wdl-lint/src/lib.rs
index 585313a89..a016430a2 100644
--- a/wdl-lint/src/lib.rs
+++ b/wdl-lint/src/lib.rs
@@ -1,5 +1,7 @@
 //! Lint rules for Workflow Description Language (WDL) documents.
 #![doc = include_str!("../RULES.md")]
+//! # Definitions
+#![doc = include_str!("../DEFINITIONS.md")]
 //! # Examples
 //!
 //! An example of parsing a WDL document and linting it:
@@ -43,6 +45,9 @@ pub use tags::*;
 pub use visitor::*;
 pub use wdl_ast as ast;
 
+/// The definitions of WDL concepts and terminology used in the linting rules.
+pub const DEFINITIONS_TEXT: &str = include_str!("../DEFINITIONS.md");
+
 /// The reserved rule identifiers that are used by analysis.
 pub const RESERVED_RULE_IDS: &[&str] = &[
     "UnusedImport",
diff --git a/wdl-lint/src/rules/malformed_lint_directive.rs b/wdl-lint/src/rules/malformed_lint_directive.rs
index 2f322a636..bd374e2ab 100644
--- a/wdl-lint/src/rules/malformed_lint_directive.rs
+++ b/wdl-lint/src/rules/malformed_lint_directive.rs
@@ -85,10 +85,10 @@ impl Rule for MalformedLintDirectiveRule {
     }
 
     fn explanation(&self) -> &'static str {
-        "Comments which begin with `#@` must only contain valid lint directives. Lint directives \
-         must be on their own line, only preceded by whitespace. Lint directives should follow the \
-         pattern `#@ <directive>: <value>` _exactly_. Currently the only accepted lint directive \
-         is `except`. For example, `#@ except: MalformedLintDirective`."
+        "This rule checks that lint directives are properly formatted.\nLint directives must be on \
+         their own line, only preceded by whitespace. They should follow the pattern `#@ \
+         <directive>: <value>` _exactly_. Currently the only accepted lint directive is `except`. \
+         For example, `#@ except: MalformedLintDirective`."
     }
 
     fn tags(&self) -> TagSet {
diff --git a/wdl-lint/src/rules/preamble_comment_after_version.rs b/wdl-lint/src/rules/preamble_comment_after_version.rs
index bc20bd0ef..9bc2599af 100644
--- a/wdl-lint/src/rules/preamble_comment_after_version.rs
+++ b/wdl-lint/src/rules/preamble_comment_after_version.rs
@@ -48,7 +48,8 @@ impl Rule for PreambleCommentAfterVersionRule {
     }
 
     fn explanation(&self) -> &'static str {
-        "Preamble comments should be inside the preamble."
+        "Preamble comments should only appear in the preamble section of a WDL document. This rule \
+         ensures that double-pound comments (`##`) are not used after the version statement."
     }
 
     fn tags(&self) -> TagSet {
diff --git a/wdl-lint/src/rules/preamble_formatting.rs b/wdl-lint/src/rules/preamble_formatting.rs
index 1ad44df9e..966baa2a1 100644
--- a/wdl-lint/src/rules/preamble_formatting.rs
+++ b/wdl-lint/src/rules/preamble_formatting.rs
@@ -120,32 +120,29 @@ impl Rule for PreambleFormattingRule {
          the version declaration statement itself. Only comments and whitespace are permitted \
          before the version declaration.
 
-         All comments in the preamble should conform to one of two special formats:
-
-            1. \"lint directives\" are special comments that begin with `#@ except:` followed by a \
-         comma-delimited list of rule IDs. These comments are used to disable specific lint rules \
-         for a specific section of the document. When a lint directive is encountered in the \
-         preamble, it will disable the specified rules for the entire document.
-            2. double-pound-sign comments (beginning with `##`) are special comments that are used \
-         for documentation that doesn't fit within any of the WDL-defined documentation elements \
-         (i.e. `meta` and `parameter_meta` sections). These comments may provide context for a \
-         collection of tasks or structs, or they may provide a high-level overview of the \
-         workflow. We refer to these special double-pound-sign comments as \"preamble comments\". \
-         Lint directives are not considered preamble comments.
-
-         Both of these comments are expected to be full line comments (i.e. they should not have \
-         any whitespace before the comment).  If lint directives are present, they should be the \
-         absolute beginning of the document. Multiple lint directives are permitted, but they \
-         should not be interleaved with preamble comments or blank lines.
-
-         A space should follow the double-pound-sign if there is any text within the preamble \
-         comment. \"Empty\" preamble comments are permitted and should not have any whitespace \
-         following the `##`. Comments beginning with 3 or more pound signs before the version \
-         declaration are not permitted. All preamble comments should be in a single block without \
-         blank lines. Following this block, there should always be a blank line before the version \
-         statement.
-
-         Both lint directives and preamble comments are optional, and if they are not present, \
+         All comments in the preamble should conform to one of two special formats: lint \
+         directives or preamble comments.
+
+         This rule enforces the following formatting requirements:
+
+         1. Comments in the preamble should be full line comments (no whitespace before the \
+         comment).
+         2. If lint directives are present, they should be at the absolute beginning of the \
+         document.
+         3. Multiple lint directives are permitted, but they should not be interleaved with \
+         preamble comments or blank lines.
+         4. A space should follow the double-pound-sign (`##`) if there is any text within the \
+         preamble comment.
+         5. \"Empty\" preamble comments (`##`) are permitted and should not have any whitespace \
+         following the `##`.
+         6. Comments beginning with 3 or more pound signs before the version declaration are not \
+         permitted.
+         7. All preamble comments should be in a single block without blank lines.
+         8. Following the preamble comment block, there should always be a blank line before the \
+         version statement.
+         9. When transitioning from lint directives to preamble comments, there should be exactly \
+         one blank line.
+         10. Both lint directives and preamble comments are optional, and if they are not present, \
          there should be no comments or whitespace before the version declaration."
     }
 


Reviews:
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T13:56:38Z
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T14:00:25Z
user: login: Gyan-max
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-28T14:01:46Z
user: login: Gyan-max
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-28T14:01:50Z
user: login: Gyan-max
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-28T14:01:54Z
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T14:03:08Z
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T14:10:23Z
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T14:30:27Z
user: login: peterhuene
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-28T15:05:56Z
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T15:11:57Z
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T15:27:17Z
user: login: peterhuene
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-28T15:37:45Z
user: login: a-frantz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-03-28T15:42:49Z
user: login: a-frantz
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-28T17:06:34Z
user: login: adthrasher
state: APPROVED
author_association: MEMBER
submitted_at: 2025-03-28T18:50:15Z

Review comments:
diff_hunk: @@ -0,0 +1,68 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives are expected to be full line comments (i.e., they should not have any whitespace before the comment). If lint directives are present, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: correction: lint directives _in the preamble_ should not have whitespace before the comment. Lint directives elsewhere in the file should match the indentation of whatever they are "commenting on"
created_at: 2025-03-28T13:44:28Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,68 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives are expected to be full line comments (i.e., they should not have any whitespace before the comment). If lint directives are present, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
+
+```wdl
+## This workflow performs RNA-seq analysis
+## It aligns reads and quantifies gene expression
+```
+
+A space should follow the double pound sign if there is any text within the preamble comment. "Empty" preamble comments are permitted and should not have any whitespace following the `##`. Comments beginning with 3 or more pound signs before the version declaration are not permitted.
+
+All preamble comments should be in a single block without blank lines. Following this block, there should always be a blank line before the version statement.
+
+### Regular Comments
+
+Regular comments begin with a single pound sign (`#`) and can appear anywhere in the document except in the preamble. These are used for inline documentation and explanations.
+
+## Metadata Sections
+
+### Meta Section
+
+The `meta` section provides metadata about a workflow, task, or other WDL element. This section can include a description of what the element does, author information, and other relevant details.
+
+### Parameter Meta Section
+
+The `parameter_meta` section provides metadata specifically about input parameters. It should include descriptions of each input parameter, including its purpose, expected format, and any constraints.
+
+## Runtime Requirements
+
+### Runtime Section
+
+The `runtime` section specifies the computational resources and environment needed to execute a task. This might include memory requirements, CPU allocation, Docker container information, and other execution environment details.
+
+### Requirements Section
+
+In WDL version 1.2 and later, the `requirements` section is used to specify additional requirements for task execution that are not directly related to computational resources, such as network access or specialized hardware needs.
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: I don't think any of this is necessary. This is all defined in the WDL SPEC proper, and we don't want to duplicate that effort.

This DEFINITIONS file should be exclusively for concepts/conventions that this repo has introduced.
created_at: 2025-03-28T13:46:50Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,68 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives are expected to be full line comments (i.e., they should not have any whitespace before the comment). If lint directives are present, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
+
+```wdl
+## This workflow performs RNA-seq analysis
+## It aligns reads and quantifies gene expression
+```
+
+A space should follow the double pound sign if there is any text within the preamble comment. "Empty" preamble comments are permitted and should not have any whitespace following the `##`. Comments beginning with 3 or more pound signs before the version declaration are not permitted.
+
+All preamble comments should be in a single block without blank lines. Following this block, there should always be a blank line before the version statement.
+
+### Regular Comments
+
+Regular comments begin with a single pound sign (`#`) and can appear anywhere in the document except in the preamble. These are used for inline documentation and explanations.
+
+## Metadata Sections
+
+### Meta Section
+
+The `meta` section provides metadata about a workflow, task, or other WDL element. This section can include a description of what the element does, author information, and other relevant details.
+
+### Parameter Meta Section
+
+The `parameter_meta` section provides metadata specifically about input parameters. It should include descriptions of each input parameter, including its purpose, expected format, and any constraints.
+
+## Runtime Requirements
+
+### Runtime Section
+
+The `runtime` section specifies the computational resources and environment needed to execute a task. This might include memory requirements, CPU allocation, Docker container information, and other execution environment details.
+
+### Requirements Section
+
+In WDL version 1.2 and later, the `requirements` section is used to specify additional requirements for task execution that are not directly related to computational resources, such as network access or specialized hardware needs.
+
+## Naming Conventions
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: Not sure if this should be here or not. I could go either way 🤔 
created_at: 2025-03-28T13:47:30Z
author_association: MEMBER
diff_hunk: @@ -1,5 +1,9 @@
 //! Lint rules for Workflow Description Language (WDL) documents.
 #![doc = include_str!("../RULES.md")]
+//! # Definitions
+//! 
+//! The following document defines key concepts and terminology used throughout the WDL linting rules.
path: wdl-lint/src/lib.rs
user: login: a-frantz
body: ```suggestion
```
the `include_str!()` macro is going to copy and paste the file comments into this doc string. So the `# Definitions` header would be duplicated, and "the following document" won't be very clear
created_at: 2025-03-28T13:49:08Z
author_association: MEMBER
diff_hunk: @@ -85,8 +85,9 @@ impl Rule for MalformedLintDirectiveRule {
     }
 
     fn explanation(&self) -> &'static str {
-        "Comments which begin with `#@` must only contain valid lint directives. Lint directives \
-         must be on their own line, only preceded by whitespace. Lint directives should follow the \
+        "This rule checks that lint directives (as defined in DEFINITIONS.md) are properly formatted. \
path: wdl-lint/src/rules/malformed_lint_directive.rs
user: login: a-frantz
body: This is going to be rendered in a variety of places (most notably `sprocket explain`) where it's not easy to determine where to look for `DEFINITIONS.md`. I'm not sure what an elegant solution is here... in the meantime I'd just remove this:
```suggestion
        "This rule checks that lint directives are properly formatted. \
```
We may want to print `DEFINITIONS.md` from `sprocket`, but I'm not sure the best way to accomplish that. I'll think on this issue some more.
created_at: 2025-03-28T13:52:27Z
author_association: MEMBER
diff_hunk: @@ -48,7 +48,9 @@ impl Rule for PreambleCommentAfterVersionRule {
     }
 
     fn explanation(&self) -> &'static str {
-        "Preamble comments should be inside the preamble."
+        "Preamble comments (as defined in DEFINITIONS.md) should only appear in the preamble section of a WDL document, \
path: wdl-lint/src/rules/preamble_comment_after_version.rs
user: login: a-frantz
body: ```suggestion
        "Preamble comments should only appear in the preamble section of a WDL document, \
```
created_at: 2025-03-28T13:54:26Z
author_association: MEMBER
diff_hunk: @@ -120,32 +120,21 @@ impl Rule for PreambleFormattingRule {
          the version declaration statement itself. Only comments and whitespace are permitted \
          before the version declaration.
          
-         All comments in the preamble should conform to one of two special formats:
-
-            1. \"lint directives\" are special comments that begin with `#@ except:` followed by a \
-         comma-delimited list of rule IDs. These comments are used to disable specific lint rules \
-         for a specific section of the document. When a lint directive is encountered in the \
-         preamble, it will disable the specified rules for the entire document.
-            2. double-pound-sign comments (beginning with `##`) are special comments that are used \
-         for documentation that doesn't fit within any of the WDL-defined documentation elements \
-         (i.e. `meta` and `parameter_meta` sections). These comments may provide context for a \
-         collection of tasks or structs, or they may provide a high-level overview of the \
-         workflow. We refer to these special double-pound-sign comments as \"preamble comments\". \
-         Lint directives are not considered preamble comments.
-
-         Both of these comments are expected to be full line comments (i.e. they should not have \
-         any whitespace before the comment).  If lint directives are present, they should be the \
-         absolute beginning of the document. Multiple lint directives are permitted, but they \
-         should not be interleaved with preamble comments or blank lines.
-         
-         A space should follow the double-pound-sign if there is any text within the preamble \
-         comment. \"Empty\" preamble comments are permitted and should not have any whitespace \
-         following the `##`. Comments beginning with 3 or more pound signs before the version \
-         declaration are not permitted. All preamble comments should be in a single block without \
-         blank lines. Following this block, there should always be a blank line before the version \
-         statement.
-         
-         Both lint directives and preamble comments are optional, and if they are not present, \
+         All comments in the preamble should conform to one of two special formats: lint directives \
+         or preamble comments, both of which are defined in detail in the DEFINITIONS.md file.
path: wdl-lint/src/rules/preamble_formatting.rs
user: login: a-frantz
body: ```suggestion
         or preamble comments.
```
created_at: 2025-03-28T13:54:53Z
author_association: MEMBER
path: wdl-lint/src/lib.rs
user: login: a-frantz
body: I'm not sure if this is ideal, but I have an idea for how to expose these definitions in sprocket:
```
pub const DEFINITIONS_TEXT = include_str!("../DEFINITIONS.md")
```
and then in sprocket, we can `use wdl::lint::DEFINITIONS_TEXT` and print it when appropriate
created_at: 2025-03-28T14:00:25Z
author_association: MEMBER
diff_hunk: @@ -1,5 +1,9 @@
 //! Lint rules for Workflow Description Language (WDL) documents.
 #![doc = include_str!("../RULES.md")]
+//! # Definitions
+//! 
+//! The following document defines key concepts and terminology used throughout the WDL linting rules.
path: wdl-lint/src/lib.rs
user: login: Gyan-max
body: Remove "The following document defines..." text before the include_str!
created_at: 2025-03-28T14:01:46Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,68 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives are expected to be full line comments (i.e., they should not have any whitespace before the comment). If lint directives are present, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
+
+```wdl
+## This workflow performs RNA-seq analysis
+## It aligns reads and quantifies gene expression
+```
+
+A space should follow the double pound sign if there is any text within the preamble comment. "Empty" preamble comments are permitted and should not have any whitespace following the `##`. Comments beginning with 3 or more pound signs before the version declaration are not permitted.
+
+All preamble comments should be in a single block without blank lines. Following this block, there should always be a blank line before the version statement.
+
+### Regular Comments
+
+Regular comments begin with a single pound sign (`#`) and can appear anywhere in the document except in the preamble. These are used for inline documentation and explanations.
+
+## Metadata Sections
+
+### Meta Section
+
+The `meta` section provides metadata about a workflow, task, or other WDL element. This section can include a description of what the element does, author information, and other relevant details.
+
+### Parameter Meta Section
+
+The `parameter_meta` section provides metadata specifically about input parameters. It should include descriptions of each input parameter, including its purpose, expected format, and any constraints.
+
+## Runtime Requirements
+
+### Runtime Section
+
+The `runtime` section specifies the computational resources and environment needed to execute a task. This might include memory requirements, CPU allocation, Docker container information, and other execution environment details.
+
+### Requirements Section
+
+In WDL version 1.2 and later, the `requirements` section is used to specify additional requirements for task execution that are not directly related to computational resources, such as network access or specialized hardware needs.
path: wdl-lint/DEFINITIONS.md
user: login: Gyan-max
body: Remove sections that duplicate the WDL spec (Regular Comments, Metadata Sections, Runtime Requirements)
created_at: 2025-03-28T14:01:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,68 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives are expected to be full line comments (i.e., they should not have any whitespace before the comment). If lint directives are present, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
path: wdl-lint/DEFINITIONS.md
user: login: Gyan-max
body: Update lint directives to specify that they should not have whitespace in the preamble (but should match indentation elsewhere)
created_at: 2025-03-28T14:01:54Z
author_association: CONTRIBUTOR
path: wdl-lint/src/lib.rs
user: login: a-frantz
body: @peterhuene what do you think about this? It feels kind of hacky. Maybe there's a more idiomatic way to accomplish this?
created_at: 2025-03-28T14:03:08Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,46 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: as we are including this in other places that aren't this document, I would just axe this introduction and jump straight into the definitions
```suggestion
```
created_at: 2025-03-28T14:06:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,46 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives in the preamble should not have any whitespace before the comment. If lint directives are present in the preamble, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: This feels like a duplication of the `PreambleFormatting` rule, so I'd remove it
```suggestion
```
created_at: 2025-03-28T14:07:54Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,46 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives in the preamble should not have any whitespace before the comment. If lint directives are present in the preamble, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
+
+Lint directives elsewhere in the file should match the indentation of whatever they are "commenting on".
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: ```suggestion
```
same here. I think we can leave the details of formatting up to the lint rules themselves.
created_at: 2025-03-28T14:08:39Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,46 @@
+# Definitions
+
+This document defines key concepts and terminology used throughout the WDL linting rules.
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+Lint directives in the preamble should not have any whitespace before the comment. If lint directives are present in the preamble, they should be at the absolute beginning of the document. Multiple lint directives are permitted, but they should not be interleaved with preamble comments or blank lines.
+
+Lint directives elsewhere in the file should match the indentation of whatever they are "commenting on".
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
+
+```wdl
+## This workflow performs RNA-seq analysis
+## It aligns reads and quantifies gene expression
+```
+
+A space should follow the double pound sign if there is any text within the preamble comment. "Empty" preamble comments are permitted and should not have any whitespace following the `##`. Comments beginning with 3 or more pound signs before the version declaration are not permitted.
+
+All preamble comments should be in a single block without blank lines. Following this block, there should always be a blank line before the version statement.
+
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: ```suggestion
```
same rationale
created_at: 2025-03-28T14:09:10Z
author_association: MEMBER
diff_hunk: @@ -48,7 +48,9 @@ impl Rule for PreambleCommentAfterVersionRule {
     }
 
     fn explanation(&self) -> &'static str {
-        "Preamble comments should be inside the preamble."
+        "Preamble comments should only appear in the preamble section of a WDL document, \
+         which is before the version statement. This rule ensures that double-pound comments (`##`) \
+         are not used after the version statement."
path: wdl-lint/src/rules/preamble_comment_after_version.rs
user: login: a-frantz
body: ```suggestion
        "Preamble comments should only appear in the preamble section of a WDL document. \
        This rule ensures that double-pound comments (`##`) \
         are not used after the version statement."
```
created_at: 2025-03-28T14:10:13Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,36 @@
+# Definitions
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: ```suggestion
Preamble comments are special comments at the start of a WDL file that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of a workflow. For example:
```
created_at: 2025-03-28T14:28:51Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,36 @@
+# Definitions
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
+
+```wdl
+## This workflow performs RNA-seq analysis
+## It aligns reads and quantifies gene expression
+```
+
+## Naming Conventions
+
+### Snake Case
+
+Snake case is a naming convention where words are written in lowercase with underscores between them (e.g., `my_variable_name`). This is the recommended convention for tasks, workflows, and variables in WDL.
+
+### Pascal Case
+
+Pascal case is a naming convention where words are written without spaces and each word starts with an uppercase letter (e.g., `MyStructName`). This is the recommended convention for struct definitions in WDL. 
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: ```suggestion
```
created_at: 2025-03-28T14:30:17Z
author_association: MEMBER
path: wdl-lint/src/lib.rs
user: login: peterhuene
body: Would we be printing it the contents even though it's markdown?

Note that we would basically be embedding the contents of the file in the executable as a string, which I'd like to avoid if possible (not that it's *huge* or anything, I just want to make sure it's worth embedding the file in terms of UX).
created_at: 2025-03-28T15:05:56Z
author_association: CONTRIBUTOR
path: wdl-lint/src/lib.rs
user: login: a-frantz
body: My idea for the UX would be that `sprocket explain` would print the contents of the markdown file to the terminal. Something like `sprocket explain --definitions` maybe? I'm not sure it's the _best_ idea, but I'm not sure how else we could get these definitions into the sprocket bin

Related - https://github.com/stjude-rust-labs/sprocket/issues/80
created_at: 2025-03-28T15:11:57Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,26 @@
+# Definitions
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
+
+```wdl
+## This workflow performs RNA-seq analysis
+## It aligns reads and quantifies gene expression
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: ```suggestion
## # FlagFilter
##
## A struct to represent the filtering flags used in various `samtools` commands.
```
copying from here - https://github.com/stjudecloud/workflows/blob/main/data_structures/flag_filter.wdl
created_at: 2025-03-28T15:25:25Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,36 @@
+# Definitions
+
+## WDL Document Structure
+
+### Preamble
+
+The document preamble is defined as anything before the version declaration statement and the version declaration statement itself. Only comments and whitespace are permitted before the version declaration.
+
+## Comment Types
+
+### Lint Directives
+
+Lint directives are special comments that begin with `#@ except:` followed by a comma-delimited list of rule IDs. These comments are used to disable specific lint rules for a section of the document. When a lint directive is encountered in the preamble, it will disable the specified rules for the entire document. For example:
+
+```wdl
+#@ except: LineWidth, CommentWhitespace
+```
+
+### Preamble Comments
+
+Preamble comments are special comments that begin with double pound signs (`##`). These comments are used for documentation that doesn't fit within any of the WDL-defined documentation elements (i.e., `meta` and `parameter_meta` sections). They may provide context for a collection of tasks or structs, or they may provide a high-level overview of the workflow. For example:
path: wdl-lint/DEFINITIONS.md
user: login: a-frantz
body: I think that we can also mention here that `wdl-doc` renders these comments as markdown.
created_at: 2025-03-28T15:27:12Z
author_association: MEMBER
path: wdl-lint/src/lib.rs
user: login: peterhuene
body: I personally don't think unrendered Markdown looks great, but that's just me.

But I'm also the kind of person that doesn't want to read a lot of text from a terminal (I even prefer man pages found online); I'd rather be presented with a link I can click on to open up a rendered web page if I want to read something akin to docs.
created_at: 2025-03-28T15:37:45Z
author_association: CONTRIBUTOR
path: wdl-lint/src/lib.rs
user: login: a-frantz
body: Sadly, no website yet :(
but I do consider the `sprocket explain` command to be the prototype for a future docs site. So from that perspective, I think it's fitting to add a `--definitions` flag to `explain`.

I don't know what will happen to `explain` once we actually get a live site, but we can burn that bridge when we get to it 🔥 
created_at: 2025-03-28T15:42:49Z
author_association: MEMBER

PR comments:
user: login: Gyan-max
created_at: 2025-03-28T16:02:41Z
body: @a-frantz Can you guide me with the failed tests?
author_association: CONTRIBUTOR
user: login: a-frantz
created_at: 2025-03-28T16:07:59Z
body: > @a-frantz Can you guide me with the failed tests?

oops, those are failing because of me. Just run the tests locally with `BLESS=1` and commit them. We can just correct the tests I goofed in this PR
author_association: MEMBER
user: login: Gyan-max
created_at: 2025-03-28T16:27:26Z
body: > > @a-frantz Can you guide me with the failed tests?
> 
> oops, those are failing because of me. Just run the tests locally with `BLESS=1` and commit them. We can just correct the tests I goofed in this PR

`$env:BLESS=1; cargo test --all-features `
this?
author_association: CONTRIBUTOR
user: login: a-frantz
created_at: 2025-03-28T16:29:48Z
body: > `$env:BLESS=1; cargo test --all-features ` this?

I think you need to run it from Bash, and that running it from a windows terminal could cause issues. But I don't know because I don't use windows
author_association: MEMBER
user: login: Gyan-max
created_at: 2025-03-28T19:08:35Z
body: @a-frantz @adthrasher thank you guys for approval!
author_association: CONTRIBUTOR