Adds extensive documentation for the Rust Oso crate.

languages/rust/oso/src/errors.rs

@@ -1,27 +1,41 @@
+//! # Error types used by the Oso library.
+//!
+//! This module contains a collection of error types that can be returned by various calls by the
+//! Oso library.
 use std::fmt;
-
 use thiserror::Error;
 
+/// Errors returned by the Polar library.
 pub use polar_core::error as polar;
 
 // TODO stack traces????
 
-/// oso errors
+/// Oso error type.
 ///
-/// TODO: fill in other variants
+/// This enum encompasses all things that can go wrong while using the Oso library. It can also be
+/// used to wrap a custom error message, using the [`OsoError::Custom`] variant or using the
+/// [`lazy_error`](crate::lazy_error) macro.
 #[allow(clippy::large_enum_variant)]
 #[derive(Error, Debug)]
 pub enum OsoError {
+    /// Input/output error.
     #[error(transparent)]
     Io(#[from] std::io::Error),
+
+    /// Polar error, see [`PolarError`](polar::PolarError).
     #[error(transparent)]
     Polar(#[from] polar::PolarError),
+
+    /// Failed to convert type from Polar.
     #[error("failed to convert type from Polar")]
     FromPolar,
+
+    /// Incorrect file name, must have `.polar` extension.
     #[error("policy files must have the .polar extension. {filename} does not.")]
     IncorrectFileType { filename: String },
 
-    #[error("Invariant error: {source}")]
+    /// Invariant error.
+    #[error(transparent)]
     InvariantError {
         #[from]
         source: InvariantError,
@@ -31,34 +45,43 @@ pub enum OsoError {
     #[error(transparent)]
     TypeError(TypeError),
 
+    /// Unsupported operation for the given type.
     #[error("Unsupported operation {operation} for type {type_name}.")]
     UnsupportedOperation {
         operation: String,
         type_name: String,
     },
 
+    /// Unimplemented operation.
     #[error("{operation} are unimplemented in the oso Rust library")]
     UnimplementedOperation { operation: String },
 
+    /// Inline query failed.
     #[error("Inline query failed {location}")]
     InlineQueryFailedError { location: String },
 
+    /// Invalid call error.
     #[error(transparent)]
     InvalidCallError(#[from] InvalidCallError),
 
+    /// Failure converting type to polar.
     #[error("failed to convert type to Polar")]
     ToPolar,
 
+    /// Class already registered.
     #[error("Class {name} already registered")]
     DuplicateClassError { name: String },
 
+    /// Missing class error.
     #[error("No class called {name} has been registered")]
     MissingClassError { name: String },
 
+    /// Missing instance error.
     #[error("Tried to find an instance that doesn't exist -- internal error")]
     MissingInstanceError,
 
-    /// TODO: replace all these with proper variants
+    // TODO: replace all these with proper variants
+    /// Custom error.
     #[error("{message}")]
     Custom { message: String },
 
@@ -92,7 +115,7 @@ impl OsoError {
     }
 }
 
-/// These are conditions that should never occur, and indicate a bug in oso.
+/// These are conditions that should never occur, and indicate a bug in Oso.
 #[derive(Error, Debug)]
 pub enum InvariantError {
     #[error("Invalid receiver for method. {0}")]
@@ -102,9 +125,14 @@ pub enum InvariantError {
     MethodNotFound,
 }
 
+/// Type error
+///
+/// This error results from using the wrong type in a place where a specific type is expected.
 #[derive(Error, Debug)]
 pub struct TypeError {
+    /// Type that was received
     pub got: Option<String>,
+    /// Type that was expected
     pub expected: String,
 }
 
@@ -146,6 +174,10 @@ impl TypeError {
     }
 }
 
+/// Invalid call error.
+///
+/// Generated when an invalid call is encountered, such as calling a method or attribute on a class
+/// that does exist.
 #[derive(Error, Debug)]
 pub enum InvalidCallError {
     #[error("Class method {method_name} not found on type {type_name}.")]
@@ -165,4 +197,8 @@ pub enum InvalidCallError {
     },
 }
 
-pub type Result<T> = std::result::Result<T, OsoError>;
+/// Convenience wrapper for Oso results.
+///
+/// This is the same as the standard library [`Result`], except that it defaults to [`OsoError`] as
+/// the error type.
+pub type Result<T, E = OsoError> = std::result::Result<T, E>;

languages/rust/oso/src/extras.rs

@@ -1,26 +1,23 @@
+#[allow(unused)]
+use crate::host::{Class, ClassBuilder};
+
 #[cfg(feature = "uuid-06")]
 impl crate::PolarClass for uuid_06::Uuid {
-    fn get_polar_class_builder() -> crate::host::ClassBuilder<uuid_06::Uuid> {
-        crate::host::Class::builder()
-            .name("Uuid")
-            .with_equality_check()
+    fn get_polar_class_builder() -> ClassBuilder<uuid_06::Uuid> {
+        Class::builder().name("Uuid").with_equality_check()
     }
 }
 
 #[cfg(feature = "uuid-07")]
 impl crate::PolarClass for uuid_07::Uuid {
-    fn get_polar_class_builder() -> crate::host::ClassBuilder<uuid_07::Uuid> {
-        crate::host::Class::builder()
-            .name("Uuid")
-            .with_equality_check()
+    fn get_polar_class_builder() -> ClassBuilder<uuid_07::Uuid> {
+        Class::builder().name("Uuid").with_equality_check()
     }
 }
 
 #[cfg(feature = "uuid-10")]
 impl crate::PolarClass for uuid_10::Uuid {
-    fn get_polar_class_builder() -> crate::host::ClassBuilder<uuid_10::Uuid> {
-        crate::host::Class::builder()
-            .name("Uuid")
-            .with_equality_check()
+    fn get_polar_class_builder() -> ClassBuilder<uuid_10::Uuid> {
+        Class::builder().name("Uuid").with_equality_check()
     }
 }