Provide more compact metadata annotation format

[anderseknert]

trafficstars

When working with many annotated packages and rules, the current "# METADATA" format for annotations feel rather verbose, and the fact that nothing else in Rego is written in capital letters makes them stand out more than they ought to. Additionally, the "# METADATA" part itself occupies a line of code that could be used for something better. Providing a more compact alternative would be nice. I suggest using ## at the beginning of a line to mean this comment is part of a metadata annotation.

old

# METADATA
# title: foo
# description: bar
allow if ...

new

## title: foo
## description: bar
allow if ...

This would also allow mixing regular comments with metadata ones all in the same block, e.g:

## title: foo
#  description below is wrong, but remains for historical reasons
## description: bar
allow if ...

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[tsandall]

This seems nice to have. I'd opt for a more explicit syntax, e.g., instead of ## use #@ or something that stands out a bit more. I know that I'll often comment out several lines while editing and sometimes that might include comments because it's just convenient. Some editors will inject a space after the comment character, others won't. I would not want that to accidentally generate a bunch of annotations.. For example:

# some comment ...
allow { input.foo == "bar" }

# some other comment ...
allow { input.foo == "baz" }

Could become:

## some comment ...
#allow { input.foo == "bar" }
#
## some other comment ...
#allow { input.foo == "baz" }

[anderseknert]

Fair point about editors. I guess a simple way to avoid that would be to say that ## and a valid metadata attribute starts a metadata block, so this would be considered one:

## title: foo

but not

##allow { input.foo == "baz" }

# or

## allow { input.foo == "baz" }

But #@ is good in that it clearly differentiates metadata comments from normal comments, so let's do that then.

#@ title: foo
#@ description: bar

[johanfylling]

Could we even simplify it further? Simply using a solitary @ as metadata prefix is easier to type (marginally 😄), and supports being commented out:

@ title: foo
@ description: bar
#@ a-commented-out-annotation
# a regular comment
@ schemas: ...

As some annotations, like schemas and entrypoint, aren't just information carriers, but actually affect compilation and eval, this would also further distinguish annotations from regular comments, which have no side effects.

[anderseknert]

Although that's an interesting idea, I think that's one step too far 😅 I think it's good to keep metadata as comments, as it feels like they logically belong in that group, should be syntax highlighted as such, etc.