8000 rune: Fix and add more documentation · rune-rs/rune@a0a0f2b · GitHub
[go: up one dir, main page]
Skip to content

Commit a0a0f2b

Browse files
udoprogudoprog
committed
rune: Fix and add more documentation
1 parent 88c9e41 commit a0a0f2b

File tree

3 files changed

+160
-86
lines changed

3 files changed

+160
-86
lines changed

‎crates/rune/src/any.rs

Lines changed: 80 additions & 79 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,86 @@ use core::any;
33
use crate::compile::Named;
44
use crate::runtime::{AnyTypeInfo, TypeHash};
55

6+
/// The trait implemented for types which can be used inside of Rune.
7+
///
8+
/// This can only be implemented correctly through the [`Any`] derive.
9+
/// Implementing it manually is not supported.
10+
///
11+
/// Rune only supports two types, *built-in* types like [`i64`] and *external*
12+
/// types which derive `Any`. Before they can be used they must be registered in
13+
/// [`Context::install`] through a [`Module`].
14+
///
15+
/// This is typically used in combination with declarative macros to register
16+
/// functions and macros, such as [`rune::function`].
17+
///
18+
/// [`AnyObj`]: crate::runtime::AnyObj
19+
/// [`Context::install`]: crate::Context::install
20+
/// [`Module`]: crate::Module
21+
/// [`String`]: std::string::String
22+
/// [`rune::function`]: macro@crate::function
23+
/// [`rune::macro_`]: macro@crate::macro_
24+
/// [`Any`]: derive@crate::Any
25+
///
26+
/// # Examples
27+
///
28+
/// ```
29+
/// use rune::Any;
30+
///
31+
/// #[derive(Any)]
32+
/// struct Npc {
33+
/// #[rune(get)]
34+
/// health: u32,
35+
/// }
36+
///
37+
/// impl Npc {
38+
/// /// Construct a new NPC.
39+
/// #[rune::function(path = Self::new)]
40+
/// fn new(health: u32) -> Self {
41+
/// Self {
42+
/// health
43+
/// }
44+
/// }
45+
///
46+
/// /// Damage the NPC with the given `amount`.
47+
/// #[rune::function]
48+
/// fn damage(&mut self, amount: u32) {
49+
/// self.health -= amount;
50+
/// }
51+
/// }
52+
///
53+
/// fn install() -> Result<rune::Module, rune::ContextError> {
54+
/// let mut module = rune::Module::new();
55+
/// module.ty::<Npc>()?;
56+
/// module.function_meta(Npc::new)?;
57+
/// module.function_meta(Npc::damage)?;
58+
/// Ok(module)
59+
/// }
60+
/// ```
61+
pub trait Any: TypeHash + Named + any::Any {
62+
/// The compile-time type information know for the type.
63+
const ANY_TYPE_INFO: AnyTypeInfo = AnyTypeInfo::new(Self::full_name, Self::HASH);
64+
}
65+
66+
/// Trait implemented for types which can be automatically converted to a
67+
/// [`Value`].
68+
///
69+
/// We can't use a blanked implementation over `T: Any` because it only governs
70+
/// what can be stored in any [`AnyObj`].
71+
///
72+
/// This trait in contrast is selectively implemented for types which we want to
73+
/// generate [`ToValue`] and [`FromValue`] implementations for.
74+
///
75+
/// [`Value`]: crate::runtime::Value
76+
/// [`AnyObj`]: crate::runtime::AnyObj
77+
/// [`ToValue`]: crate::runtime::ToValue
78+
/// [`FromValue`]: crate::runtime::FromValue
79+
///
80+
/// Note that you are *not* supposed to implement this directly. Make use of the
81+
/// [`Any`] derive instead.
82+
///
83+
/// [`Any`]: derive@crate::Any
84+
pub trait AnyMarker: Any {}
85+
686
/// Macro to mark a value as external, which will implement all the appropriate
787
/// traits.
888
///
@@ -226,82 +306,3 @@ use crate::runtime::{AnyTypeInfo, TypeHash};
226306
/// [`rune::alloc`]: crate::alloc
227307
/// [`TryClone` trait]: crate::alloc::clone::TryClone
228308
pub use rune_macros::Any;
229-
230-
/// Derive for types which can be used inside of Rune.
231-
///
232-
/// Rune only supports two types, *built-in* types [`String`] and *external*
233-
/// types which derive `Any`. Before they can be used they must be registered in
234-
/// [`Context::install`] through a [`Module`].
235-
///
236-
/// This is typically used in combination with declarative macros to register
237-
/// functions and macros, such as:
238-
///
239-
/// * [`#[rune::function]`]
240-
/// * [`#[rune::macro_]`]
241-
///
242-
/// [`AnyObj`]: crate::runtime::AnyObj
243-
/// [`Context::install`]: crate::Context::install
244-
/// [`Module`]: crate::Module
245-
/// [`String`]: std::string::String
246-
/// [`#[rune::function]`]: macro@crate::function
247-
/// [`#[rune::macro_]`]: crate::macro_
248-
///
249-
/// # Examples
250-
///
251-
/// ```
252-
/// use rune::Any;
253-
///
254-
/// #[derive(Any)]
255-
/// struct Npc {
256-
/// #[rune(get)]
257-
/// health: u32,
258-
/// }
259-
///
260-
/// impl Npc {
261-
/// /// Construct a new NPC.
262-
/// #[rune::function(path = Self::new)]
263-
/// fn new(health: u32) -> Self {
264-
/// Self {
265-
/// health
266-
/// }
267-
/// }
268-
///
269-
/// /// Damage the NPC with the given `amount`.
270-
/// #[rune::function]
271-
/// fn damage(&mut self, amount: u32) {
272-
/// self.health -= amount;
273-
/// }
274-
/// }
275-
///
276-
/// fn install() -> Result<rune::Module, rune::ContextError> {
277-
/// let mut module = rune::Module::new();
278-
/// module.ty::<Npc>()?;
279-
/// module.function_meta(Npc::new)?;
280-
/// module.function_meta(Npc::damage)?;
281-
/// Ok(module)
282-
/// }
283-
/// ```
284-
pub trait Any: TypeHash + Named + any::Any {
285-
/// The compile-time type information know for the type.
286-
const ANY_TYPE_INFO: AnyTypeInfo = AnyTypeInfo::new(Self::full_name, Self::HASH);
287-
}
288-
289-
/// Trait implemented for types which can be automatically converted to a
290-
/// [`Value`].
291-
///
292-
/// We can't use a blanked implementation over `T: Any` because it only governs
293-
/// what can be stored in any [`AnyObj`].
294-
///
295-
/// This trait in contrast is selectively implemented for types which we want to
296-
/// generate [`ToValue`] and [`FromValue`] implementations for.
297-
///
298-
/// [`Value`]: crate::runtime::Value
299-
/// [`AnyObj`]: crate::runtime::AnyObj
300-
/// [`ToValue`]: crate::runtime::ToValue
301-
/// [`FromValue`]: crate::runtime::FromValue
302-
///
303-
/// Note that you are *not* supposed to implement this directly. Make use of the
304-
/// [`Any`] derive instead.
305-
///
306-
/// [`Any`]: derive@Any
307-
pub trait AnyMarker: Any {}

‎crates/rune/src/lib.rs

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -202,6 +202,7 @@ pub mod fmt;
202202
pub use ::codespan_reporting::term::termcolor;
203203

204204
pub(crate) mod any;
205+
#[doc(inline)]
205206
pub use self::any::Any;
206207

207208
mod build;
@@ -254,8 +255,8 @@ pub mod query;
254255
pub mod runtime;
255256
#[doc(inline)]
256257
pub use self::runtime::{
257-
from_const_value, from_value, to_const_value, to_value, FromValue, Mut, Ref, ToConstValue,
258-
ToValue, TypeHash, Unit, Value, Vm,
258+
from_const_value, from_value, to_const_value, to_value, FromConstValue, FromValue, Mut, Ref,
259+
ToConstValue, ToValue, TypeHash, Unit, Value, Vm,
259260
};
260261

261262
mod shared;

‎crates/rune/src/runtime/const_value.rs

Lines changed: 77 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,77 @@ use super::{
2323
VmErrorKind,
2424
};
2525

26-
/// Derive for the [`ToConstValue`](trait@ToConstValue) trait.
26+
/// Derive for the [`ToConstValue`] trait.
27+
///
28+
/// This is principally used for associated constants in native modules, since
29+
/// Rune has to be provided a constant-compatible method for constructing values
30+
/// of the given type.
31+
///
32+
/// [`ToConstValue`]: trait@crate::ToConstValue
33+
///
34+
/// # Examples
35+
///
36+
/// ```
37+
/// use rune::{docstring, Any, ContextError, Module, ToConstValue};
38+
///
39+
/// #[derive(Any, ToConstValue)]
40+
/// pub struct Duration {
41+
/// #[const_value(with = const_duration)]
42+
/// inner: std::time::Duration,
43+
/// }
44+
///
45+
/// mod const_duration {
46+
/// use rune::runtime::{ConstValue, RuntimeError, Value};
47+
/// use std::time::Duration;
48+
///
49+
/// #[inline]
50+
/// pub(super) fn to_const_value(duration: Duration) -> Result<ConstValue, RuntimeError> {
51+
/// let secs = duration.as_secs();
52+
/// let nanos = duration.subsec_nanos();
53+
/// rune::to_const_value((secs, nanos))
54+
/// }
55+
///
56+
/// #[inline]
57+
/// pub(super) fn from_const_value(value: &ConstValue) -> Result<Duration, RuntimeError> {
58+
/// let (secs, nanos) = rune::from_const_value::<(u64, u32)>(value)?;
59+
/// Ok(Duration::new(secs, nanos))
60+
/// }
61+
///
62+
/// #[inline]
63+
/// pub(super) fn from_value(value: Value) -> Result<Duration, RuntimeError> {
64+
/// let (secs, nanos) = rune::from_value::<(u64, u32)>(value)?;
65+
/// Ok(Duration::new(secs, nanos))
66+
/// }
67+
/// }
68+
///
69+
/// #[rune::module(::time)]
70+
/// pub fn module() -> Result<Module, ContextError> {
71+
/// let mut m = Module::from_meta(module__meta)?;
72+
/// m.ty::<Duration>()?;
73+
///
74+
/// m
75+
/// .constant(
76+
/// "SECOND",
77+
/// Duration {
78+
/// inner: std::time::Duration::from_secs(1),
79+
/// },
80+
/// )
81+
/// .build_associated::<Duration>()?
82+
/// .docs(docstring! {
83+
/// /// The duration of one second.
84+
/// ///
85+
/// /// # Examples
86+
/// ///
87+
/// /// ```rune
88+
/// /// use time::Duration;
89+
/// ///
90+
/// /// let duration = Duration::SECOND;
91+
/// /// ```
92+
/// })?;
93+
///
94+
/// Ok(m)
95+
/// }
96+
/// ```
2797
pub use rune_macros::ToConstValue;
2898

2999
use super::{AnyTypeInfo, RuntimeError, VmIntegerRepr};
@@ -84,13 +154,14 @@ pub fn to_const_value(value: impl ToConstValue) -> Result<ConstValue, RuntimeErr
84154
value.to_const_value()
85155
}
86156

87-
/// Convert a value into a constant value.
157+
/// Trait to perform a conversion to a [`ConstValue`].
88158
pub trait ToConstValue: Sized {
89159
/// Convert into a constant value.
90160
fn to_const_value(self) -> Result<ConstValue, RuntimeError>;
91161

92162
/// Return the constant constructor for the given type.
93163
#[inline]
164+
#[doc(hidden)]
94165
fn construct() -> Option<Arc<dyn ConstConstruct>> {
95166
None
96167
}
@@ -460,7 +531,7 @@ impl fmt::Debug for ConstValue {
460531
}
461532
}
462533

463-
/// Convert a value from a constant value.
534+
/// Trait to perform a conversion from a [`ConstValue`].
464535
pub trait FromConstValue: Sized {
465536
/// Convert from a constant value.
466537
fn from_const_value(value: ConstValue) -> Result<Self, RuntimeError>;
@@ -475,8 +546,9 @@ impl FromConstValue for ConstValue {
475546

476547
/// Implementation of a constant constructor.
477548
///
478-
/// Do not implement manually, this is provided when deriving
479-
/// [`ToConstValue`](derive@ToConstValue).
549+
/// Do not implement manually, this is provided when deriving [`ToConstValue`].
550+
///
551+
/// [`ToConstValue`]: derive@ToConstValue
480552
pub trait ConstConstruct: 'static + Send + Sync {
481553
/// Construct from values.
482554
#[doc(hidden)]

0 commit comments

Comments
 (0)
0