Adds extensive documentation for the Rust Oso crate.

[xfbs]

This fills out any public documentation and adds code examples where possible. In a few places, the code was cleaned up a little bit. No logic was changed of any kind.

I have made one change, but this should be an overall improvement and is not an API change:

The Result type that Oso exposes was changed slightly from

type Result<T> = std::result::Result<T, OsoError>;

to

type Result<T, E = OsoError> = std::result::Result<T, E>;

This makes it more useful: now you can write Result<String> and it will mean Result<String, OsoError>, but you can still manually override the error type by writing Result<String, IoError>. The same approach is taken by anyhow::Result. Since this Result type is just an alias, and because this does not affect existing usages (only relaxes the restriction, such that more parameters can be specified), it does not consitute a breaking change and does not need to be reflected by a version bump.

I'm not sure if this needs to go into the changelog, if so feel free to add it.

[github-actions[bot]]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅