is our block description syntax valid yaml?

[williballenthin]

currently, we allow rule authors to add a description to and/or/etc. like so:

and:
  - match: foo
  - match: bar
  description: this is awesome!

(concrete example here)

this seemed like a natural way to extend our two-line syntax for feature descriptions, which look like:

and:
  - string: foo
    description: bar

however, i'm not sure that the former is valid yaml. ruamel accepts it, but pyyaml does not. take a moment to look at it and try to figure out how it should be parsed? is the child of the and a list or dictionary???

[williballenthin]

one way to make this work while only slightly tweaking the syntax is to make description an element in the list, like:

and:
  - match: foo
  - match: bar
  - description: this is awesome!

[williballenthin]

downside: fixing up this syntax is technically a breaking change, affecting the last minor version or so. the alternative is to suffer having rules that are maybe not valid yaml (something I think is fairly important).

personally, I probably prefer to keep things as we intended and make the change (violating semver and assuming no one will notice).

[williballenthin]

upside: the description can now be placed at the top of a block, like:

and:
  - description: everything is awesome!
  - match: foo
  - match: bar

I think all our rules with the conflicting syntax have the description as the last element, which I personally find hard to follow, all because this is all that ruamel accepted.

[williballenthin]

maybe for v1.3.0 we should comment out these description lines as they currently exist so we can fully discuss the changes here while minimizing the time the invalid syntax exists.

[williballenthin]

tagging @re-fox since I know they have used this syntax to make rules easier to read

[mr-tz]

Yeah, let's fix this. Commenting out is a good start!

[re-fox]

I agree! That sounds like a good plan.

I remember at the time, modifying the rule several times before I found a working variation. I think that's how I ended up on.

  - api: foo
  description: bar

In my opinion it's better to have commented descriptions than none at all. Those can always be uncommented and fixed up later.