From 4aa9e1fcdd881e22aed792abae97965e3ca93c99 Mon Sep 17 00:00:00 2001
From: John-John Tedro <udoprog@tedro.se>
Date: Sun, 7 Apr 2024 10:37:44 +0200
Subject: [PATCH] Improve Any derive documentation

---
 crates/rune/src/any.rs | 52 +++++++++++++++++++++++++++++++++++-------
 crates/rune/src/lib.rs |  6 ++++-
 2 files changed, 49 insertions(+), 9 deletions(-)

diff --git a/crates/rune/src/any.rs b/crates/rune/src/any.rs
index 0ccbb8464..0224d2cc3 100644
--- a/crates/rune/src/any.rs
+++ b/crates/rune/src/any.rs
@@ -56,26 +56,62 @@ use crate::hash::Hash;
 /// ```
 pub use rune_macros::Any;
 
-/// A trait which can be stored inside of an [AnyObj](crate::runtime::AnyObj).
+/// Derive for types which can be used inside of Rune.
 ///
-/// We use our own marker trait that must be explicitly derived to prevent other
-/// VM native types (like strings) which also implement `std::any::Any` from
-/// being stored as an `AnyObj`.
+/// Rune only supports two types, *built-in* types [`String`] and *external*
+/// types which derive `Any`. Before they can be used they must be registered in
+/// [`Context::install`] through a [`Module`].
 ///
-/// This means, that only types which derive `Any` can be used inside of the VM:
+/// This is typically used in combination with declarative macros to register
+/// functions and macros, such as:
+///
+/// * [`#[rune::function]`]
+/// * [`#[rune::macro_]`]
+///
+/// [`AnyObj`]: crate::runtime::AnyObj
+/// [`Context::install`]: crate::Context::install
+/// [`Module`]: crate::Module
+/// [`String`]: std::string::String
+/// [`#[rune::function]`]: crate::function
+/// [`#[rune::macro_]`]: crate::macro_
+///
+/// # Examples
 ///
 /// ```
 /// use rune::Any;
 ///
 /// #[derive(Any)]
 /// struct Npc {
-///     name: String,
+///     #[rune(get)]
+///     health: u32,
+/// }
+///
+/// impl Npc {
+///     /// Construct a new NPC.
+///     #[rune::function(path = Self::new)]
+///     fn new(health: u32) -> Self {
+///         Self {
+///             health
+///         }
+///     }
+///
+///     /// Damage the NPC with the given `amount`.
+///     #[rune::function]
+///     fn damage(&mut self, amount: u32) {
+///         self.health -= amount;
+///     }
+/// }
+///
+/// fn install() -> Result<rune::Module, rune::ContextError> {
+///     let mut module = rune::Module::new();
+///     module.ty::<Npc>()?;
+///     module.function_meta(Npc::new)?;
+///     module.function_meta(Npc::damage)?;
+///     Ok(module)
 /// }
 /// ```
 pub trait Any: Named + any::Any {
     /// The type hash of the type.
-    ///
-    /// TODO: make const field when `TypeId::of` is const.
     fn type_hash() -> Hash;
 }
 
diff --git a/crates/rune/src/lib.rs b/crates/rune/src/lib.rs
index 98e9f0556..06807fe78 100644
--- a/crates/rune/src/lib.rs
+++ b/crates/rune/src/lib.rs
@@ -184,7 +184,7 @@ pub mod alloc;
 #[cfg(test)]
 pub(crate) mod testing;
 
-/// Helper prelude for #[no_std] support.
+/// Helper prelude for `#[no_std]` support.
 pub mod no_std;
 
 #[macro_use]
@@ -200,6 +200,7 @@ pub mod ast;
 pub mod fmt;
 
 cfg_emit! {
+    #[doc(inline)]
     pub use ::codespan_reporting::term::termcolor;
 }
 
@@ -243,15 +244,18 @@ pub mod parse;
 pub mod query;
 
 pub mod runtime;
+#[doc(inline)]
 pub use self::runtime::{from_value, to_value, FromValue, ToValue, Unit, Value, Vm};
 
 mod shared;
 
 pub mod source;
+#[doc(inline)]
 pub use self::source::Source;
 
 #[macro_use]
 mod sources;
+#[doc(inline)]
 pub use self::sources::{SourceId, Sources};
 
 mod worker;