[Cedar Doc Issue] Add explanations of error messages

[mwhicks1]

Request: Cedar error messages, from the validator and evaluator, can be confusing because of the lack of context. We should provide explanations and examples for the messages in the documentation.

Example: cedar-policy/cedar#103 describes how the error

Error: Validation error on policy XXX: Policy is impossible. The policy expression evaluates to false for all valid requests

can be confusing because it's not clear what sub-expression in the policy is causing the policy to always evaluate to false. But there's a bigger problem: Users may not even know what "policy expression evaluates to false for all valid requests" even means. They need to understand what the message is trying to communicate so they can try to debug their policy.

Proposal: Add a section to the documentation called EXPLANATION OF ERRORS, perhaps toward the end. This will have two parts: One for validation errors and one for evaluation/authorization errors. In each, have a table of error messages, with links to explanations for individual messages. The explanations could have three parts: (1) Error (what is the error text), (2) Explanation (a textual explanation of what the error means), and (3) Example (an example policy/schema/etc. that exhibits the error).

For our example, we could write

Error: Policy is impossible. The policy expression evaluates to false for all valid requests
Explanation: The validator has determined that there is no request that can possibly satisfy this policy. To make this determination, the validator considers all legal requests that conform to the schema. It finds that for none of them will the policy ever evaluate to true. Usually the reason for this is some condition in the policy that can never be true, which thus causes the whole policy to always be unsatisfied.
Example: Suppose we have the policy permit(principal,action,resource) when { resource has Owner && resource.Owner == principal }; and we attempt to validate it under this schema. According to the actions part of the schema, for all legal actions the resource could be either List or Application, but neither of these entities (again, per the schema) can ever have an Owner attribute. This means that the expression resource has Owner in the when clause will always evaluate to false, which always makes the whole policy false. This situation arises from a presumed typo: A List can have attribute owner, but Cedar is case sensitive: Owner and owner are not the same thing.

[john-h-kastner-aws]

We likely want to do this with cedar-policy/cedar#184 so that users have an easy and persistent way to find error in the docs. We'll also want to add #[diagnostic(url("docs.cedarpolicy.com/errors/{error_code}"))] annotation to our errors.

[mwhicks1]

This issue requests an explanation of errors for Cedar users who are not likely to look at the Rust docs. Are you thinking that the Rust docs would link to the explanation on the main documentation pages?

[cdisselkoen]

Yes, @john-h-kastner-aws' suggestion would result in the Rust docs linking to these docs.cedarpolicy.com error explanations