docs(policy-reference): add more examples for existing built-in functions

[srenatus]

The policy reference contains a list of all the built-in functions; and examples for very few. It would be helpful for getting off the ground if some basic examples showed to to use a built-in.

This issue is broad and not meant to be fixed in a single sweep. Any added examples will be valuable.

[stale[bot]]

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

[Joffref]

At this time on-boarding some built-in functions is quite hard such as graph related functions.

I think this a good pick, I would enjoy to participate, is it possible to create a draft PR ?

I there a list (with prioritization) of function that need documentation ?

[srenatus]

I've got ideas about how to deal with this, centered around well-annotated example rego files.

So if you'd like to pick a builtin to document, please create a rego file like docs/examples/io.jwt.decode_verify.rego,

package examples.builtins.io.jwt.decode_verify

# METADATA
# description: |
#   When used in a simple case, io.jwt.decode_verify does this and that.
test_simple {
  jwt := "..."
  criteria := { }
  io.jwt.decode_verify(jwt, criteria) == { ... }
}

# METADATA
# description: To check issuer, the `iss` criterium needs to be provided
test_issuer {
  # ...
}

with a few of these in place, we can then worry about hooking them into the website docs automatically, which is a bit of a different story.