revise: wordsmith the explanation tags

[Pabsthegreat]

Requested change in issue #116 and wordsmithing explanation() texts

Before submitting this PR, please make sure:

• You have added a few sentences describing the PR here.
• You have added yourself or the appropriate individual as the assignee.
• You have added at least one relevant code reviewer to the PR.
• Your code builds clean without any errors or warnings.
• You have added an entry to the relevant CHANGELOG.md (see
  "keep a changelog" for more information).
• Your commit messages follow the conventional commit style.
• Your PR title follows the conventional commit style.

[Pabsthegreat]

@a-frantz I'll try to flag some explanation tags that seem a little hard to understand in these comments. If there a better way to flag them please let me know. Also do I need to log an entry in CHANGELOG right now since this is quite a small edit?Thanks!

[a-frantz]

If there a better way to flag them please let me know.

You can also create a thread in the #lib-wf-wdl GSoC slack channel! That should be a bit easier to discuss in.

Also do I need to log an entry in CHANGELOG right now since this is quite a small edit?

I'd wait for now, and add the CHANGELOG entry right before you mark this PR as ready for review.

[Pabsthegreat]

I did go through some explanation texts, one thing I felt is including examples will be extremely helpful since they illustrate what the text is saying especially in long explanations like in expression_spacing.rs. I don't know if that will greatly increase the length of explanation but it sure would help in long explanations covering many rules. If readability is the aim and length is not an issue, then examples could get the point across without someone reading the text since code is sometimes easier to understand. @a-frantz

[Pabsthegreat]

If there a better way to flag them please let me know.

You can also create a thread in the #lib-wf-wdl GSoC slack channel! That should be a bit easier to discuss in.

Also do I need to log an entry in CHANGELOG right now since this is quite a small edit?

I'd wait for now, and add the CHANGELOG entry right before you mark this PR as ready for review.

yes i will do that, thank you

[a-frantz]

I did go through some explanation texts, one thing I felt is including examples will be extremely helpful since they illustrate what the text is saying especially in long explanations like in expression_spacing.rs. I don't know if that will greatly increase the length of explanation but it sure would help in long explanations covering many rules. @a-frantz

Examples would be great! I'm just not sure the best way to include them 🤔 I don't think they fit in the explanation() text itself, as that is more meant to be a justification for why the rule exists. So including examples there seems incongruous to me.

Perhaps we can add an examples() method to the Rule trait?

I'm open to ideas! But brainstorming is probably best done in the Slack to avoid too much noise here on github.

[Pabsthegreat]

I did go through some explanation texts, one thing I felt is including examples will be extremely helpful since they illustrate what the text is saying especially in long explanations like in expression_spacing.rs. I don't know if that will greatly increase the length of explanation but it sure would help in long explanations covering many rules. @a-frantz

Examples would be great! I'm just not sure the best way to include them 🤔 I don't think they fit in the explanation() text itself, as that is more meant to be a justification for why the rule exists. So including examples there seems incongruous to me.

Perhaps we can add an examples() method to the Rule trait?

I'm open to ideas! But brainstorming is probably best done in the Slack to avoid too much noise here on github.

yes adding an examples() method might be great, yes ill move this conversation to Slack now. Thanks @a-frantz

[Pabsthegreat]

@a-frantz @adthrasher could you please check what went wrong with the CI checks?

[claymcleod]

Just in general, when referring to a literal code block (meta, parameter_meta, output), I'd wrap it in backticks to remain consistent with what we've done in the past.

[claymcleod]

Can you please fix the outstanding CI issue?