rune: Re-export and document Mut and Ref

crates/rune/src/lib.rs

@@ -255,8 +255,8 @@ pub mod query;
 pub mod runtime;
 #[doc(inline)]
 pub use self::runtime::{
-    from_const_value, from_value, to_const_value, to_value, FromValue, ToConstValue, ToValue,
-    TypeHash, Unit, Value, Vm,
+    from_const_value, from_value, to_const_value, to_value, FromValue, Mut, Ref, ToConstValue,
+    ToValue, TypeHash, Unit, Value, Vm,
 };
 
 mod shared;

crates/rune/src/module/module.rs

@@ -733,8 +733,7 @@ impl Module {
     /// # Examples
     ///
     /// ```
-    /// use rune::{Module, ContextError};
-    /// use rune::runtime::Ref;
+    /// use rune::{ContextError, Module, Ref};
     ///
     /// /// This is a pretty neat function.
     /// #[rune::function]
@@ -759,8 +758,7 @@ impl Module {
     /// Registering instance functions:
     ///
     /// ```
-    /// use rune::{Any, Module};
-    /// use rune::runtime::Ref;
+    /// use rune::{Any, Module, Ref};
     ///
     /// #[derive(Any)]
     /// struct MyBytes {
@@ -1063,8 +1061,7 @@ impl Module {
     /// use std::sync::atomic::AtomicU32;
     /// use std::sync::Arc;
     ///
-    /// use rune::{Any, Module};
-    /// use rune::runtime::Ref;
+    /// use rune::{Any, Module, Ref};
     ///
     /// #[derive(Clone, Debug, Any)]
     /// struct Client {

crates/rune/src/runtime/ref.rs

@@ -16,7 +16,17 @@ pub(super) struct RefVtable {
 
 type DropFn = unsafe fn(NonNull<()>);
 
-/// A strong reference to the given type.
+/// A strong owned reference to the given type that can be safely dereferenced.
+///
+/// # Examples
+///
+/// Constructed from a static value:
+///
+/// ```rust
+/// use rune::Ref;
+///
+/// let value: Ref<str> = Ref::from_static("hello world");
+/// ```
 pub struct Ref<T: ?Sized> {
     value: NonNull<T>,
     guard: RawAnyGuard,
@@ -30,7 +40,7 @@ impl<T> From<Rc<T>> for Ref<T> {
     ///
     /// ```
     /// use std::rc::Rc;
-    /// use rune::runtime::Ref;
+    /// use rune::Ref;
     ///
     /// let value: Ref<String> = Ref::from(Rc::new(String::from("hello world")));
     /// assert_eq!(value.as_ref(), "hello world");
@@ -57,7 +67,7 @@ impl<T> From<Arc<T>> for Ref<T> {
     ///
     /// ```
     /// use std::sync::Arc;
-    /// use rune::runtime::Ref;
+    /// use rune::Ref;
     ///
     /// let value: Ref<String> = Ref::from(Arc::new(String::from("hello world")));
     /// assert_eq!(value.as_ref(), "hello world");
@@ -81,7 +91,16 @@ impl<T: ?Sized> Ref<T> {
         Self { value, guard }
     }
 
-    /// Construct a static reference.
+    /// Construct an owned reference from a static value.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use rune::Ref;
+    ///
+    /// let value: Ref<str> = Ref::from_static("Hello World");
+    /// assert_eq!(value.as_ref(), "Hello World");
+    /// ```
     pub const fn from_static(value: &'static T) -> Ref<T> {
         let value = unsafe { NonNull::new_unchecked((value as *const T).cast_mut()) };
         let guard = RawAnyGuard::new(NonNull::dangling(), &RefVtable { drop: |_| {} });
@@ -93,7 +112,8 @@ impl<T: ?Sized> Ref<T> {
     /// # Examples
     ///
     /// ```
-    /// use rune::runtime::{Bytes, Ref};
+    /// use rune::Ref;
+    /// use rune::runtime::Bytes;
     /// use rune::alloc::try_vec;
     ///
     /// let bytes = rune::to_value(Bytes::from_vec(try_vec![1, 2, 3, 4]))?;
@@ -123,7 +143,8 @@ impl<T: ?Sized> Ref<T> {
     /// # Examples
     ///
     /// ```
-    /// use rune::runtime::{Bytes, Ref};
+    /// use rune::Ref;
+    /// use rune::runtime::Bytes;
     /// use rune::alloc::try_vec;
     ///
     /// let bytes = rune::to_value(Bytes::from_vec(try_vec![1, 2, 3, 4]))?;
@@ -206,7 +227,19 @@ where
     }
 }
 
-/// A strong mutable reference to the given type.
+/// A strong owned mutable reference to the given type that can be safely
+/// dereferenced.
+///
+/// # Examples
+///
+/// Constructed from a static value:
+///
+/// ```rust
+/// use rune::Mut;
+///
+/// let value: Mut<[u8]> = Mut::from_static(&mut [][..]);
+/// assert_eq!(&value[..], b"");
+/// ```
 pub struct Mut<T: ?Sized> {
     value: NonNull<T>,
     guard: RawAnyGuard,
@@ -217,7 +250,16 @@ impl<T: ?Sized> Mut<T> {
         Self { value, guard }
     }
 
-    /// Construct a static mutable reference.
+    /// Construct an owned mutable reference from a static value.
+    ///
+    /// # Examples
+    ///
+    /// ```rust
+    /// use rune::Mut;
+    ///
+    /// let value: Mut<[u8]> = Mut::from_static(&mut [][..]);
+    /// assert_eq!(&value[..], b"");
+    /// ```
     pub fn from_static(value: &'static mut T) -> Mut<T> {
         let value = unsafe { NonNull::new_unchecked((value as *const T).cast_mut()) };
         let guard = RawAnyGuard::new(NonNull::dangling(), &RefVtable { drop: |_| {} });
@@ -229,7 +271,8 @@ impl<T: ?Sized> Mut<T> {
     /// # Examples
     ///
     /// ```
-    /// use rune::runtime::{Bytes, Mut};
+    /// use rune::Mut;
+    /// use rune::runtime::Bytes;
     /// use rune::alloc::try_vec;
     ///
     /// let bytes = rune::to_value(Bytes::from_vec(try_vec![1, 2, 3, 4]))?;
@@ -260,7 +303,8 @@ impl<T: ?Sized> Mut<T> {
     /// # Examples
     ///
     /// ```
-    /// use rune::runtime::{Bytes, Mut};
+    /// use rune::Mut;
+    /// use rune::runtime::Bytes;
     /// use rune::alloc::try_vec;
     ///
     /// let bytes = rune::to_value(Bytes::from_vec(try_vec![1, 2, 3, 4]))?;

crates/rune/src/runtime/value.rs

@@ -1083,23 +1083,27 @@ impl Value {
     /// Try to coerce value into a typed mutable reference of type `T`.
     ///
     /// You should usually prefer to use [`rune::from_value`] instead of this
-    /// directly.
+    /// directly since it supports transparently coercing into types like
+    /// [`Mut<str>`].
     ///
     /// [`rune::from_value`]: crate::from_value
     ///
     /// # Examples
     ///
     /// ```rust
-    /// use rune::Value;
+    /// use rune::{Mut, Value};
     /// use rune::alloc::String;
     ///
     /// let mut a = Value::try_from("Hello World")?;
     /// let b = a.clone();
     ///
-    /// let s = a.into_mut::<String>()?;
-    /// assert_eq!(s.as_str(), "Hello World");
-    /// s.make_ascii_lowercase();
-    /// assert_eq!(s.as_str(), "hello world");
+    /// fn modify_string(mut s: Mut<String>) {
+    ///     assert_eq!(s.as_str(), "Hello World");
+    ///     s.make_ascii_lowercase();
+    ///     assert_eq!(s.as_str(), "hello world");
+    /// }
+    ///
+    /// modify_string(a.into_mut::<String>()?);
     ///
     /// assert_eq!(b.borrow_mut::<String>()?.as_str(), "hello world");
     /// # Ok::<_, rune::support::Error>(())

crates/rune/src/runtime/vm.rs

@@ -469,12 +469,12 @@ impl Vm {
     /// # Panics
     ///
     /// If any of the arguments passed in are references, and that references is
-    /// captured somewhere in the call as [`Mut<T>`] or [`Ref<T>`]
-    /// this call will panic as we are trying to free the metadata relatedc to
-    /// the reference.
+    /// captured somewhere in the call as [`Mut<T>`] or [`Ref<T>`] this call
+    /// will panic as we are trying to free the metadata relatedc to the
+    /// reference.
     ///
-    /// [`Mut<T>`]: runtime::Mut
-    /// [`Ref<T>`]: runtime::Ref
+    /// [`Mut<T>`]: crate::Mut
+    /// [`Ref<T>`]: crate::Ref
     pub fn call(
         &mut self,
         name: impl ToTypeHash,
@@ -509,12 +509,12 @@ impl Vm {
     /// # Panics
     ///
     /// If any of the arguments passed in are references, and that references is
-    /// captured somewhere in the call as [`Mut<T>`] or [`Ref<T>`]
-    /// this call will panic as we are trying to free the metadata relatedc to
-    /// the reference.
+    /// captured somewhere in the call as [`Mut<T>`] or [`Ref<T>`] this call
+    /// will panic as we are trying to free the metadata relatedc to the
+    /// reference.
     ///
-    /// [`Mut<T>`]: runtime::Mut
-    /// [`Ref<T>`]: runtime::Ref
+    /// [`Mut<T>`]: crate::Mut
+    /// [`Ref<T>`]: crate::Ref
     pub fn call_with_diagnostics(
         &mut self,
         name: impl ToTypeHash,