Adds some documentation and examples (#1697)

Co-authored-by: Gabe Jackson <17556281+gj@users.noreply.github.com>

languages/rust/oso/src/host/class.rs

@@ -47,10 +47,20 @@ fn iterator_not_supported() -> IteratorMethod {
     Arc::new(into_iter)
 }
 
+/// Class that can be registered with [`Oso`](crate::Oso).
+///
+/// A class represents an entity, such as an *actor* or a *resource*. It is typically backed by
+/// a Rust struct and can carry some internal state, as well as have methods that can be made
+/// accessible from within the policy file.
+///
+/// While the instance of the class itself is stored as a [`PolarValue::Instance`], the [`Class`]
+/// struct contains metadata, such as the constructor, attributes, instance methods, comparison
+/// functions as well as the name.
 #[derive(Clone)]
 pub struct Class {
-    /// The class name. Defaults to the `std::any::type_name`
+    /// The class name. Defaults to [`std::any::type_name`].
     pub name: String,
+    /// Type ID of the class.
     pub type_id: TypeId,
     /// A wrapped method that constructs an instance of `T` from `PolarValue`s
     constructor: Option<Constructor>,
@@ -67,15 +77,20 @@ pub struct Class {
 
     into_iter: IteratorMethod,
 
-    // Hooks to be called on the class once it's been registered with host.
+    /// Hooks to be called on the class once it's been registered with host.
     pub register_hooks: RegisterHooks,
 }
 
 impl Class {
+    /// Builder instance to build class.
+    ///
+    /// Use this when you want to hook your own class into [`Oso`](crate::Oso).
+    /// See [`ClassBuilder`] for usage examples.
     pub fn builder<T: 'static>() -> ClassBuilder<T> {
         ClassBuilder::new()
     }
 
+    /// Initialize new class instance.
     pub fn init(&self, fields: Vec<PolarValue>) -> crate::Result<Instance> {
         if let Some(constructor) = &self.constructor {
             constructor.invoke(fields)
@@ -88,7 +103,7 @@ impl Class {
 
     /// Call class method `attr` on `self` with arguments from `args`.
     ///
-    /// Returns: The result as a `PolarValue`
+    /// Returns the result as a `PolarValue`.
     pub fn call(&self, attr: &str, args: Vec<PolarValue>) -> crate::Result<PolarValue> {
         let attr =
             self.class_methods
@@ -122,6 +137,16 @@ impl Class {
     }
 }
 
+/// Builder for new Oso [`Class`].
+///
+/// This helps you create a `Class` instance which holds metadata for your custom type. Using the
+/// builder, you can add attribute getters, class methods, instance methods, constants, iterator
+/// methods, override the class name, set the constructor or equality check.
+///
+/// You can create a new instance of [`ClassBuilder`] using
+/// [`PolarClass::get_polar_class_builder()`](crate::PolarClass::get_polar_class_builder), using
+/// [`Class::builder()`] or using one of the [`ClassBuilder::with_default()`] or
+/// [`ClassBuilder::with_constructor()`] methods.
 #[derive(Clone)]
 pub struct ClassBuilder<T> {
     class: Class,
@@ -153,7 +178,23 @@ where
         }
     }
 
-    /// Create a new class builder for a type that implements Default and use that as the constructor.
+    /// Create a new class builder for a type that implements [`Default`] and use that as the
+    /// constructor.
+    ///
+    /// This is equivalent to setting the constructor to [`Default::default()`].
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use oso::ClassBuilder;
+    ///
+    /// #[derive(Default)]
+    /// struct MyClass;
+    ///
+    /// let class = ClassBuilder::<MyClass>::with_default().build();
+    /// ```
     pub fn with_default() -> Self
     where
         T: std::default::Default,
@@ -163,6 +204,19 @@ where
     }
 
     /// Create a new class builder with a given constructor.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use oso::ClassBuilder;
+    ///
+    /// struct MyClass(u16);
+    ///
+    /// let class = ClassBuilder::<MyClass>::with_constructor(|| MyClass(42)).build();
+    ///
+    /// ```
     pub fn with_constructor<F, Args>(f: F) -> Self
     where
         F: Function<Args, Result = T>,
@@ -175,6 +229,12 @@ where
     }
 
     /// Set the constructor function to use for polar `new` statements.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use oso::ClassBuilder;
+    /// ```
     pub fn set_constructor<F, Args>(mut self, f: F) -> Self
     where
         F: Function<Args, Result = T>,
@@ -186,6 +246,21 @@ where
     }
 
     /// Set an equality function to be used for polar `==` statements.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use oso::ClassBuilder;
+    ///
+    /// #[derive(Default)]
+    /// struct MyClass;
+    ///
+    /// let class = ClassBuilder::<MyClass>::with_default()
+    ///     .set_equality_check(|left, right| true)
+    ///     .build();
+    /// ```
     pub fn set_equality_check<F>(mut self, f: F) -> Self
     where
         F: Fn(&T, &T) -> bool + Send + Sync + 'static,
@@ -230,16 +305,55 @@ where
         self.set_into_iter(|t| t.clone().into_iter())
     }
 
-    /// Use PartialEq::eq as the equality check for polar `==` statements.
+    /// Use [`PartialEq`] as the equality check for Polar `==` statements.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use oso::ClassBuilder;
+    ///
+    /// #[derive(Default, PartialEq)]
+    /// struct MyClass(u64);
+    ///
+    /// let class = ClassBuilder::<MyClass>::with_default()
+    ///     .with_equality_check()
+    ///     .build();
+    /// ```
     pub fn with_equality_check(self) -> Self
     where
         T: PartialEq<T>,
     {
         self.set_equality_check(|a, b| PartialEq::eq(a, b))
     }
 
-    /// Add an attribute getter for statements like `foo.bar`
-    /// `class.add_attribute_getter("bar", |instance| instance.bar)
+    /// Add an attribute getter.
+    ///
+    /// An attribute getter allows you to write statements like `foo.bar`, where `foo` is a class
+    /// instance and `bar` is an attribute.
+    ///
+    /// Typically, if you use the [`PolarClass`] derive macro, you can use `#[polar(attribute)]` to
+    /// generate this automatically.
+    ///
+    /// # Examples
+    ///
+    /// Basic usage:
+    ///
+    /// ```
+    /// use oso::ClassBuilder;
+    ///
+    /// #[derive(Default)]
+    /// struct MyClass {
+    ///     name: String,
+    ///     age: u32,
+    /// };
+    ///
+    /// let class = ClassBuilder::<MyClass>::with_default()
+    ///     .add_attribute_getter("name", |instance| instance.name.clone())
+    ///     .add_attribute_getter("age", |instance| instance.age)
+    ///     .build();
+    /// ```
     pub fn add_attribute_getter<F, R>(mut self, name: &'static str, f: F) -> Self
     where
         F: Fn(&T) -> R + Send + Sync + 'static,

languages/rust/oso/src/host/to_polar.rs

@@ -12,26 +12,48 @@ use crate::PolarValue;
 
 /// Convert Rust types to Polar types.
 ///
-/// This trait is automatically implemented for any
-/// type that implements the `PolarClass` marker trait,
-/// which should be preferred.
+/// This trait is automatically implemented for any type that implements the [`PolarClass`] marker
+/// trait, which should be preferred. You can use the [`PolarClass`](oso_derive::PolarClass) derive
+/// macro to derive that trait.
 ///
-/// This is also implemented automatically using the
-/// `#[derive(PolarClass)]` macro.
+/// For non-primitive types, the instance will be stored on the provided `Host`.
 ///
-/// For non-primitive types, the instance will be stored
-/// on the provided `Host`.
+/// # Trait bounds
 ///
-/// ## Trait bounds
+/// The default implementation for [`PolarClass`] requires types to be [`Send`] and [`Sync`], since
+/// it is possible to store a [`ToPolar`] value on an [`Oso`](crate::Oso) instance which can be
+/// shared between threads.
 ///
-/// The default implementation for `PolarClass`
-/// requires types to be `Send + Sync`, since it
-/// is possible to store a `ToPolar` value on an `Oso` instance
-/// which can be shared between threads.
+/// [`ToPolar`] implementors must also be concrete, sized types without any borrows.
 ///
-/// `ToPolar` implementors must also be concrete, sized types without
-/// any borrows.
+/// # Examples
+///
+/// Convert a primitive type into a polar value:
+///
+/// ```rust
+/// use oso::{PolarValue, ToPolar};
+///
+/// let string = "This is a string";
+/// let value = string.to_polar();
+///
+/// assert_eq!(value, PolarValue::String(string.into()));
+/// ```
+///
+/// Convert a custom type into a polar value:
+///
+/// ```
+/// use oso::{PolarValue, PolarClass, ToPolar};
+///
+/// #[derive(PolarClass)]
+/// struct MyClass;
+///
+/// let class = MyClass;
+/// let value = class.to_polar();
+///
+/// assert!(matches!(value, PolarValue::Instance(_)));
+/// ```
 pub trait ToPolar {
+    /// Convert this value into a Polar value.
     fn to_polar(self) -> PolarValue;
 }
 
@@ -81,7 +103,42 @@ mod private {
     pub trait Sealed {}
 }
 
+/// Convert tuples to Polar types.
+///
+/// This is a helper trait to convert Rust tuples (of types which implement [`ToPolar`]) into a
+/// [`Vec<PolarValue>`].
+///
+/// # Examples
+///
+/// Empty tuple:
+///
+/// ```
+/// use oso::ToPolarList;
+///
+/// assert_eq!(().to_polar_list(), vec![]);
+/// ```
+///
+/// Mixed tuples:
+///
+/// ```rust
+/// use oso::{PolarValue, PolarClass, ToPolarList};
+///
+/// #[derive(PolarClass)]
+/// struct MyClass;
+///
+/// let class = MyClass;
+/// let string = "Hello, World!";
+/// let number = 42;
+///
+/// let list = (class, string, number).to_polar_list();
+///
+/// assert_eq!(list.len(), 3);
+/// assert!(matches!(list[0], PolarValue::Instance(_)));
+/// assert_eq!(list[1], PolarValue::String(string.to_string()));
+/// assert_eq!(list[2], PolarValue::Integer(number));
+/// ```
 pub trait ToPolarList: private::Sealed {
+    /// Convert these values into an array of Polar values.
     fn to_polar_list(self) -> Vec<PolarValue>
     where
         Self: Sized;