deny(missing_docs) for bevy_reflect (#19481)

## Objective

Deny missing docs in bevy_reflect, towards
https://github.com/bevyengine/bevy/issues/3492.

## Solution

Add the missing docs!

## Testing

N/A
This commit is contained in:
theotherphil 2025-06-16 22:26:24 +01:00 committed by GitHub
parent 6db71367d4
commit 3b25b38bdc
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
29 changed files with 229 additions and 9 deletions

View File

@ -167,6 +167,7 @@ pub struct DynamicArray {
} }
impl DynamicArray { impl DynamicArray {
/// Creates a new [`DynamicArray`].
#[inline] #[inline]
pub fn new(values: Box<[Box<dyn PartialReflect>]>) -> Self { pub fn new(values: Box<[Box<dyn PartialReflect>]>) -> Self {
Self { Self {

View File

@ -1,3 +1,5 @@
//! Types and functions for creating, manipulating and querying [`CustomAttributes`].
use crate::Reflect; use crate::Reflect;
use alloc::boxed::Box; use alloc::boxed::Box;
use bevy_utils::TypeIdMap; use bevy_utils::TypeIdMap;
@ -98,16 +100,19 @@ struct CustomAttribute {
} }
impl CustomAttribute { impl CustomAttribute {
/// Creates a new [`CustomAttribute`] containing `value`.
pub fn new<T: Reflect>(value: T) -> Self { pub fn new<T: Reflect>(value: T) -> Self {
Self { Self {
value: Box::new(value), value: Box::new(value),
} }
} }
/// Returns a reference to the attribute's value if it is of type `T`, or [`None`] if not.
pub fn value<T: Reflect>(&self) -> Option<&T> { pub fn value<T: Reflect>(&self) -> Option<&T> {
self.value.downcast_ref() self.value.downcast_ref()
} }
/// Returns a reference to the attribute's value as a [`Reflect`] trait object.
pub fn reflect_value(&self) -> &dyn Reflect { pub fn reflect_value(&self) -> &dyn Reflect {
&*self.value &*self.value
} }

View File

@ -13,9 +13,12 @@ use derive_more::derive::From;
/// A dynamic representation of an enum variant. /// A dynamic representation of an enum variant.
#[derive(Debug, Default, From)] #[derive(Debug, Default, From)]
pub enum DynamicVariant { pub enum DynamicVariant {
/// A unit variant.
#[default] #[default]
Unit, Unit,
/// A tuple variant.
Tuple(DynamicTuple), Tuple(DynamicTuple),
/// A struct variant.
Struct(DynamicStruct), Struct(DynamicStruct),
} }

View File

@ -263,6 +263,7 @@ pub struct VariantFieldIter<'a> {
} }
impl<'a> VariantFieldIter<'a> { impl<'a> VariantFieldIter<'a> {
/// Creates a new [`VariantFieldIter`].
pub fn new(container: &'a dyn Enum) -> Self { pub fn new(container: &'a dyn Enum) -> Self {
Self { Self {
container, container,
@ -295,12 +296,16 @@ impl<'a> Iterator for VariantFieldIter<'a> {
impl<'a> ExactSizeIterator for VariantFieldIter<'a> {} impl<'a> ExactSizeIterator for VariantFieldIter<'a> {}
/// A field in the current enum variant.
pub enum VariantField<'a> { pub enum VariantField<'a> {
/// The name and value of a field in a struct variant.
Struct(&'a str, &'a dyn PartialReflect), Struct(&'a str, &'a dyn PartialReflect),
/// The value of a field in a tuple variant.
Tuple(&'a dyn PartialReflect), Tuple(&'a dyn PartialReflect),
} }
impl<'a> VariantField<'a> { impl<'a> VariantField<'a> {
/// Returns the name of a struct variant field, or [`None`] for a tuple variant field.
pub fn name(&self) -> Option<&'a str> { pub fn name(&self) -> Option<&'a str> {
if let Self::Struct(name, ..) = self { if let Self::Struct(name, ..) = self {
Some(*name) Some(*name)
@ -309,6 +314,7 @@ impl<'a> VariantField<'a> {
} }
} }
/// Gets a reference to the value of this field.
pub fn value(&self) -> &'a dyn PartialReflect { pub fn value(&self) -> &'a dyn PartialReflect {
match *self { match *self {
Self::Struct(_, value) | Self::Tuple(value) => value, Self::Struct(_, value) | Self::Tuple(value) => value,

View File

@ -47,7 +47,9 @@ pub enum VariantInfoError {
/// [type]: VariantType /// [type]: VariantType
#[error("variant type mismatch: expected {expected:?}, received {received:?}")] #[error("variant type mismatch: expected {expected:?}, received {received:?}")]
TypeMismatch { TypeMismatch {
/// Expected variant type.
expected: VariantType, expected: VariantType,
/// Received variant type.
received: VariantType, received: VariantType,
}, },
} }
@ -84,6 +86,7 @@ pub enum VariantInfo {
} }
impl VariantInfo { impl VariantInfo {
/// The name of the enum variant.
pub fn name(&self) -> &'static str { pub fn name(&self) -> &'static str {
match self { match self {
Self::Struct(info) => info.name(), Self::Struct(info) => info.name(),

View File

@ -11,14 +11,20 @@ pub enum ReflectCloneError {
/// ///
/// [`PartialReflect::reflect_clone`]: crate::PartialReflect::reflect_clone /// [`PartialReflect::reflect_clone`]: crate::PartialReflect::reflect_clone
#[error("`PartialReflect::reflect_clone` not implemented for `{type_path}`")] #[error("`PartialReflect::reflect_clone` not implemented for `{type_path}`")]
NotImplemented { type_path: Cow<'static, str> }, NotImplemented {
/// The fully qualified path of the type that [`PartialReflect::reflect_clone`](crate::PartialReflect::reflect_clone) is not implemented for.
type_path: Cow<'static, str>,
},
/// The type cannot be cloned via [`PartialReflect::reflect_clone`]. /// The type cannot be cloned via [`PartialReflect::reflect_clone`].
/// ///
/// This type should be returned when a type is intentionally opting out of reflection cloning. /// This type should be returned when a type is intentionally opting out of reflection cloning.
/// ///
/// [`PartialReflect::reflect_clone`]: crate::PartialReflect::reflect_clone /// [`PartialReflect::reflect_clone`]: crate::PartialReflect::reflect_clone
#[error("`{type_path}` cannot be made cloneable for `PartialReflect::reflect_clone`")] #[error("`{type_path}` cannot be made cloneable for `PartialReflect::reflect_clone`")]
NotCloneable { type_path: Cow<'static, str> }, NotCloneable {
/// The fully qualified path of the type that cannot be cloned via [`PartialReflect::reflect_clone`](crate::PartialReflect::reflect_clone).
type_path: Cow<'static, str>,
},
/// The field cannot be cloned via [`PartialReflect::reflect_clone`]. /// The field cannot be cloned via [`PartialReflect::reflect_clone`].
/// ///
/// When [deriving `Reflect`], this usually means that a field marked with `#[reflect(ignore)]` /// When [deriving `Reflect`], this usually means that a field marked with `#[reflect(ignore)]`
@ -33,8 +39,11 @@ pub enum ReflectCloneError {
full_path(.field, .variant.as_deref(), .container_type_path) full_path(.field, .variant.as_deref(), .container_type_path)
)] )]
FieldNotCloneable { FieldNotCloneable {
/// Struct field or enum variant field which cannot be cloned.
field: FieldId, field: FieldId,
/// Variant this field is part of if the container is an enum, otherwise [`None`].
variant: Option<Cow<'static, str>>, variant: Option<Cow<'static, str>>,
/// Fully qualified path of the type containing this field.
container_type_path: Cow<'static, str>, container_type_path: Cow<'static, str>,
}, },
/// Could not downcast to the expected type. /// Could not downcast to the expected type.
@ -44,7 +53,9 @@ pub enum ReflectCloneError {
/// [`Reflect`]: crate::Reflect /// [`Reflect`]: crate::Reflect
#[error("expected downcast to `{expected}`, but received `{received}`")] #[error("expected downcast to `{expected}`, but received `{received}`")]
FailedDowncast { FailedDowncast {
/// The fully qualified path of the type that was expected.
expected: Cow<'static, str>, expected: Cow<'static, str>,
/// The fully qualified path of the type that was received.
received: Cow<'static, str>, received: Cow<'static, str>,
}, },
} }

View File

@ -82,6 +82,7 @@ pub struct UnnamedField {
} }
impl UnnamedField { impl UnnamedField {
/// Create a new [`UnnamedField`].
pub fn new<T: PartialReflect + MaybeTyped + TypePath>(index: usize) -> Self { pub fn new<T: PartialReflect + MaybeTyped + TypePath>(index: usize) -> Self {
Self { Self {
index, index,
@ -135,7 +136,9 @@ impl UnnamedField {
/// A representation of a field's accessor. /// A representation of a field's accessor.
#[derive(Clone, Debug, PartialEq, Eq)] #[derive(Clone, Debug, PartialEq, Eq)]
pub enum FieldId { pub enum FieldId {
/// Access a field by name.
Named(Cow<'static, str>), Named(Cow<'static, str>),
/// Access a field by index.
Unnamed(usize), Unnamed(usize),
} }

View File

@ -196,8 +196,11 @@ impl<'a> Arg<'a> {
/// [`DynamicFunctionMut`]: crate::func::DynamicFunctionMut /// [`DynamicFunctionMut`]: crate::func::DynamicFunctionMut
#[derive(Debug)] #[derive(Debug)]
pub enum ArgValue<'a> { pub enum ArgValue<'a> {
/// An owned argument.
Owned(Box<dyn PartialReflect>), Owned(Box<dyn PartialReflect>),
/// An immutable reference argument.
Ref(&'a dyn PartialReflect), Ref(&'a dyn PartialReflect),
/// A mutable reference argument.
Mut(&'a mut dyn PartialReflect), Mut(&'a mut dyn PartialReflect),
} }

View File

@ -12,15 +12,21 @@ pub enum ArgError {
/// The argument is not the expected type. /// The argument is not the expected type.
#[error("expected `{expected}` but received `{received}` (@ argument index {index})")] #[error("expected `{expected}` but received `{received}` (@ argument index {index})")]
UnexpectedType { UnexpectedType {
/// Argument index.
index: usize, index: usize,
/// Expected argument type path.
expected: Cow<'static, str>, expected: Cow<'static, str>,
/// Received argument type path.
received: Cow<'static, str>, received: Cow<'static, str>,
}, },
/// The argument has the wrong ownership. /// The argument has the wrong ownership.
#[error("expected {expected} value but received {received} value (@ argument index {index})")] #[error("expected {expected} value but received {received} value (@ argument index {index})")]
InvalidOwnership { InvalidOwnership {
/// Argument index.
index: usize, index: usize,
/// Expected ownership.
expected: Ownership, expected: Ownership,
/// Received ownership.
received: Ownership, received: Ownership,
}, },
/// Occurs when attempting to access an argument from an empty [`ArgList`]. /// Occurs when attempting to access an argument from an empty [`ArgList`].

View File

@ -18,11 +18,18 @@ pub enum FunctionError {
ArgError(#[from] ArgError), ArgError(#[from] ArgError),
/// The number of arguments provided does not match the expected number. /// The number of arguments provided does not match the expected number.
#[error("received {received} arguments but expected one of {expected:?}")] #[error("received {received} arguments but expected one of {expected:?}")]
ArgCountMismatch { expected: ArgCount, received: usize }, ArgCountMismatch {
/// Expected argument count. [`ArgCount`] for overloaded functions will contain multiple possible counts.
expected: ArgCount,
/// Number of arguments received.
received: usize,
},
/// No overload was found for the given set of arguments. /// No overload was found for the given set of arguments.
#[error("no overload found for arguments with signature `{received:?}`, expected one of `{expected:?}`")] #[error("no overload found for arguments with signature `{received:?}`, expected one of `{expected:?}`")]
NoOverload { NoOverload {
/// The set of available argument signatures.
expected: HashSet<ArgumentSignature>, expected: HashSet<ArgumentSignature>,
/// The received argument signature.
received: ArgumentSignature, received: ArgumentSignature,
}, },
} }
@ -47,6 +54,9 @@ pub enum FunctionOverloadError {
/// An error that occurs when attempting to add a function overload with a duplicate signature. /// An error that occurs when attempting to add a function overload with a duplicate signature.
#[error("could not add function overload: duplicate found for signature `{0:?}`")] #[error("could not add function overload: duplicate found for signature `{0:?}`")]
DuplicateSignature(ArgumentSignature), DuplicateSignature(ArgumentSignature),
/// An attempt was made to add an overload with more than [`ArgCount::MAX_COUNT`] arguments.
///
/// [`ArgCount::MAX_COUNT`]: crate::func::args::ArgCount
#[error( #[error(
"argument signature `{:?}` has too many arguments (max {})", "argument signature `{:?}` has too many arguments (max {})",
0, 0,

View File

@ -235,6 +235,12 @@ impl<const N: usize> TryFrom<[SignatureInfo; N]> for FunctionInfo {
} }
} }
/// Type information for the signature of a [`DynamicFunction`] or [`DynamicFunctionMut`].
///
/// Every [`FunctionInfo`] contains one or more [`SignatureInfo`]s.
///
/// [`DynamicFunction`]: crate::func::DynamicFunction
/// [`DynamicFunctionMut`]: crate::func::DynamicFunctionMut
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
pub struct SignatureInfo { pub struct SignatureInfo {
name: Option<Cow<'static, str>>, name: Option<Cow<'static, str>>,

View File

@ -42,7 +42,7 @@
//! //!
//! A "function" is a callable that does not capture its environment. //! A "function" is a callable that does not capture its environment.
//! These are typically defined with the `fn` keyword, which are referred to as _named_ functions. //! These are typically defined with the `fn` keyword, which are referred to as _named_ functions.
//! But they are also _anonymous_ functions, which are unnamed and defined with anonymous function syntax. //! But there are also _anonymous_ functions, which are unnamed and defined with anonymous function syntax.
//! //!
//! ```rust //! ```rust
//! // This is a named function: //! // This is a named function:

View File

@ -336,6 +336,7 @@ impl Debug for FunctionRegistry {
/// A synchronized wrapper around a [`FunctionRegistry`]. /// A synchronized wrapper around a [`FunctionRegistry`].
#[derive(Clone, Default, Debug)] #[derive(Clone, Default, Debug)]
pub struct FunctionRegistryArc { pub struct FunctionRegistryArc {
/// The wrapped [`FunctionRegistry`].
pub internal: Arc<RwLock<FunctionRegistry>>, pub internal: Arc<RwLock<FunctionRegistry>>,
} }

View File

@ -134,7 +134,9 @@ macro_rules! impl_reflect_kind_conversions {
#[derive(Debug, Error)] #[derive(Debug, Error)]
#[error("kind mismatch: expected {expected:?}, received {received:?}")] #[error("kind mismatch: expected {expected:?}, received {received:?}")]
pub struct ReflectKindMismatchError { pub struct ReflectKindMismatchError {
/// Expected kind.
pub expected: ReflectKind, pub expected: ReflectKind,
/// Received kind.
pub received: ReflectKind, pub received: ReflectKind,
} }
@ -176,16 +178,46 @@ macro_rules! impl_cast_method {
/// ///
/// ["kinds"]: ReflectKind /// ["kinds"]: ReflectKind
pub enum ReflectRef<'a> { pub enum ReflectRef<'a> {
/// An immutable reference to a [struct-like] type.
///
/// [struct-like]: Struct
Struct(&'a dyn Struct), Struct(&'a dyn Struct),
/// An immutable reference to a [tuple-struct-like] type.
///
/// [tuple-struct-like]: TupleStruct
TupleStruct(&'a dyn TupleStruct), TupleStruct(&'a dyn TupleStruct),
/// An immutable reference to a [tuple-like] type.
///
/// [tuple-like]: Tuple
Tuple(&'a dyn Tuple), Tuple(&'a dyn Tuple),
/// An immutable reference to a [list-like] type.
///
/// [list-like]: List
List(&'a dyn List), List(&'a dyn List),
/// An immutable reference to an [array-like] type.
///
/// [array-like]: Array
Array(&'a dyn Array), Array(&'a dyn Array),
/// An immutable reference to a [map-like] type.
///
/// [map-like]: Map
Map(&'a dyn Map), Map(&'a dyn Map),
/// An immutable reference to a [set-like] type.
///
/// [set-like]: Set
Set(&'a dyn Set), Set(&'a dyn Set),
/// An immutable reference to an [enum-like] type.
///
/// [enum-like]: Enum
Enum(&'a dyn Enum), Enum(&'a dyn Enum),
/// An immutable reference to a [function-like] type.
///
/// [function-like]: Function
#[cfg(feature = "functions")] #[cfg(feature = "functions")]
Function(&'a dyn Function), Function(&'a dyn Function),
/// An immutable refeence to an [opaque] type.
///
/// [opaque]: ReflectKind::Opaque
Opaque(&'a dyn PartialReflect), Opaque(&'a dyn PartialReflect),
} }
impl_reflect_kind_conversions!(ReflectRef<'_>); impl_reflect_kind_conversions!(ReflectRef<'_>);
@ -211,16 +243,46 @@ impl<'a> ReflectRef<'a> {
/// ///
/// ["kinds"]: ReflectKind /// ["kinds"]: ReflectKind
pub enum ReflectMut<'a> { pub enum ReflectMut<'a> {
/// A mutable reference to a [struct-like] type.
///
/// [struct-like]: Struct
Struct(&'a mut dyn Struct), Struct(&'a mut dyn Struct),
/// A mutable reference to a [tuple-struct-like] type.
///
/// [tuple-struct-like]: TupleStruct
TupleStruct(&'a mut dyn TupleStruct), TupleStruct(&'a mut dyn TupleStruct),
/// A mutable reference to a [tuple-like] type.
///
/// [tuple-like]: Tuple
Tuple(&'a mut dyn Tuple), Tuple(&'a mut dyn Tuple),
/// A mutable reference to a [list-like] type.
///
/// [list-like]: List
List(&'a mut dyn List), List(&'a mut dyn List),
/// A mutable reference to an [array-like] type.
///
/// [array-like]: Array
Array(&'a mut dyn Array), Array(&'a mut dyn Array),
/// A mutable reference to a [map-like] type.
///
/// [map-like]: Map
Map(&'a mut dyn Map), Map(&'a mut dyn Map),
/// A mutable reference to a [set-like] type.
///
/// [set-like]: Set
Set(&'a mut dyn Set), Set(&'a mut dyn Set),
/// A mutable reference to an [enum-like] type.
///
/// [enum-like]: Enum
Enum(&'a mut dyn Enum), Enum(&'a mut dyn Enum),
#[cfg(feature = "functions")] #[cfg(feature = "functions")]
/// A mutable reference to a [function-like] type.
///
/// [function-like]: Function
Function(&'a mut dyn Function), Function(&'a mut dyn Function),
/// A mutable refeence to an [opaque] type.
///
/// [opaque]: ReflectKind::Opaque
Opaque(&'a mut dyn PartialReflect), Opaque(&'a mut dyn PartialReflect),
} }
impl_reflect_kind_conversions!(ReflectMut<'_>); impl_reflect_kind_conversions!(ReflectMut<'_>);
@ -246,16 +308,46 @@ impl<'a> ReflectMut<'a> {
/// ///
/// ["kinds"]: ReflectKind /// ["kinds"]: ReflectKind
pub enum ReflectOwned { pub enum ReflectOwned {
/// An owned [struct-like] type.
///
/// [struct-like]: Struct
Struct(Box<dyn Struct>), Struct(Box<dyn Struct>),
/// An owned [tuple-struct-like] type.
///
/// [tuple-struct-like]: TupleStruct
TupleStruct(Box<dyn TupleStruct>), TupleStruct(Box<dyn TupleStruct>),
/// An owned [tuple-like] type.
///
/// [tuple-like]: Tuple
Tuple(Box<dyn Tuple>), Tuple(Box<dyn Tuple>),
/// An owned [list-like] type.
///
/// [list-like]: List
List(Box<dyn List>), List(Box<dyn List>),
/// An owned [array-like] type.
///
/// [array-like]: Array
Array(Box<dyn Array>), Array(Box<dyn Array>),
/// An owned [map-like] type.
///
/// [map-like]: Map
Map(Box<dyn Map>), Map(Box<dyn Map>),
/// An owned [set-like] type.
///
/// [set-like]: Set
Set(Box<dyn Set>), Set(Box<dyn Set>),
/// An owned [enum-like] type.
///
/// [enum-like]: Enum
Enum(Box<dyn Enum>), Enum(Box<dyn Enum>),
/// An owned [function-like] type.
///
/// [function-like]: Function
#[cfg(feature = "functions")] #[cfg(feature = "functions")]
Function(Box<dyn Function>), Function(Box<dyn Function>),
/// An owned [opaque] type.
///
/// [opaque]: ReflectKind::Opaque
Opaque(Box<dyn PartialReflect>), Opaque(Box<dyn PartialReflect>),
} }
impl_reflect_kind_conversions!(ReflectOwned); impl_reflect_kind_conversions!(ReflectOwned);

View File

@ -1,4 +1,3 @@
#![expect(missing_docs, reason = "Not all docs are written yet, see #3492.")]
#![cfg_attr( #![cfg_attr(
any(docsrs, docsrs_dep), any(docsrs, docsrs_dep),
expect( expect(

View File

@ -192,6 +192,8 @@ impl MapInfo {
impl_generic_info_methods!(generics); impl_generic_info_methods!(generics);
} }
/// Used to produce an error message when an attempt is made to hash
/// a [`PartialReflect`] value that does not support hashing.
#[macro_export] #[macro_export]
macro_rules! hash_error { macro_rules! hash_error {
( $key:expr ) => {{ ( $key:expr ) => {{

View File

@ -21,32 +21,47 @@ pub enum ApplyError {
#[error("attempted to apply `{from_kind}` to `{to_kind}`")] #[error("attempted to apply `{from_kind}` to `{to_kind}`")]
/// Attempted to apply the wrong [kind](ReflectKind) to a type, e.g. a struct to an enum. /// Attempted to apply the wrong [kind](ReflectKind) to a type, e.g. a struct to an enum.
MismatchedKinds { MismatchedKinds {
/// Kind of the value we attempted to apply.
from_kind: ReflectKind, from_kind: ReflectKind,
/// Kind of the type we attempted to apply the value to.
to_kind: ReflectKind, to_kind: ReflectKind,
}, },
#[error("enum variant `{variant_name}` doesn't have a field named `{field_name}`")] #[error("enum variant `{variant_name}` doesn't have a field named `{field_name}`")]
/// Enum variant that we tried to apply to was missing a field. /// Enum variant that we tried to apply to was missing a field.
MissingEnumField { MissingEnumField {
/// Name of the enum variant.
variant_name: Box<str>, variant_name: Box<str>,
/// Name of the missing field.
field_name: Box<str>, field_name: Box<str>,
}, },
#[error("`{from_type}` is not `{to_type}`")] #[error("`{from_type}` is not `{to_type}`")]
/// Tried to apply incompatible types. /// Tried to apply incompatible types.
MismatchedTypes { MismatchedTypes {
/// Type of the value we attempted to apply.
from_type: Box<str>, from_type: Box<str>,
/// Type we attempted to apply the value to.
to_type: Box<str>, to_type: Box<str>,
}, },
#[error("attempted to apply type with {from_size} size to a type with {to_size} size")] #[error("attempted to apply type with {from_size} size to a type with {to_size} size")]
/// Attempted to apply to types with mismatched sizes, e.g. a [u8; 4] to [u8; 3]. /// Attempted to apply an [array-like] type to another of different size, e.g. a [u8; 4] to [u8; 3].
DifferentSize { from_size: usize, to_size: usize }, ///
/// [array-like]: crate::Array
DifferentSize {
/// Size of the value we attempted to apply, in elements.
from_size: usize,
/// Size of the type we attempted to apply the value to, in elements.
to_size: usize,
},
#[error("variant with name `{variant_name}` does not exist on enum `{enum_name}`")] #[error("variant with name `{variant_name}` does not exist on enum `{enum_name}`")]
/// The enum we tried to apply to didn't contain a variant with the give name. /// The enum we tried to apply to didn't contain a variant with the give name.
UnknownVariant { UnknownVariant {
/// Name of the enum.
enum_name: Box<str>, enum_name: Box<str>,
/// Name of the missing variant.
variant_name: Box<str>, variant_name: Box<str>,
}, },
} }

View File

@ -42,6 +42,9 @@ use serde::Deserializer;
/// [`ReflectDeserializer`]: crate::serde::ReflectDeserializer /// [`ReflectDeserializer`]: crate::serde::ReflectDeserializer
/// [via the registry]: TypeRegistry::register_type_data /// [via the registry]: TypeRegistry::register_type_data
pub trait DeserializeWithRegistry<'de>: Sized { pub trait DeserializeWithRegistry<'de>: Sized {
/// Deserialize this value using the given [Deserializer] and [`TypeRegistry`].
///
/// [`Deserializer`]: ::serde::Deserializer
fn deserialize<D>(deserializer: D, registry: &TypeRegistry) -> Result<Self, D::Error> fn deserialize<D>(deserializer: D, registry: &TypeRegistry) -> Result<Self, D::Error>
where where
D: Deserializer<'de>; D: Deserializer<'de>;

View File

@ -15,6 +15,7 @@ pub struct TypeRegistrationDeserializer<'a> {
} }
impl<'a> TypeRegistrationDeserializer<'a> { impl<'a> TypeRegistrationDeserializer<'a> {
/// Creates a new [`TypeRegistrationDeserializer`].
pub fn new(registry: &'a TypeRegistry) -> Self { pub fn new(registry: &'a TypeRegistry) -> Self {
Self { registry } Self { registry }
} }

View File

@ -1,3 +1,5 @@
//! Serde integration for reflected types.
mod de; mod de;
mod ser; mod ser;
mod type_data; mod type_data;

View File

@ -3,7 +3,9 @@ use core::ops::Deref;
/// A type-erased serializable value. /// A type-erased serializable value.
pub enum Serializable<'a> { pub enum Serializable<'a> {
/// An owned serializable value.
Owned(Box<dyn erased_serde::Serialize + 'a>), Owned(Box<dyn erased_serde::Serialize + 'a>),
/// An immutable reference to a serializable value.
Borrowed(&'a dyn erased_serde::Serialize), Borrowed(&'a dyn erased_serde::Serialize),
} }

View File

@ -40,6 +40,9 @@ use serde::{Serialize, Serializer};
/// [`ReflectSerializer`]: crate::serde::ReflectSerializer /// [`ReflectSerializer`]: crate::serde::ReflectSerializer
/// [via the registry]: TypeRegistry::register_type_data /// [via the registry]: TypeRegistry::register_type_data
pub trait SerializeWithRegistry { pub trait SerializeWithRegistry {
/// Serialize this value using the given [Serializer] and [`TypeRegistry`].
///
/// [`Serializer`]: ::serde::Serializer
fn serialize<S>(&self, serializer: S, registry: &TypeRegistry) -> Result<S::Ok, S::Error> fn serialize<S>(&self, serializer: S, registry: &TypeRegistry) -> Result<S::Ok, S::Error>
where where
S: Serializer; S: Serializer;

View File

@ -1,3 +1,5 @@
//! Module containing the [`ReflectDefault`] type.
use crate::{FromType, Reflect}; use crate::{FromType, Reflect};
use alloc::boxed::Box; use alloc::boxed::Box;
@ -10,6 +12,7 @@ pub struct ReflectDefault {
} }
impl ReflectDefault { impl ReflectDefault {
/// Returns the default value for a type.
pub fn default(&self) -> Box<dyn Reflect> { pub fn default(&self) -> Box<dyn Reflect> {
(self.default)() (self.default)()
} }

View File

@ -71,6 +71,7 @@ pub trait Struct: PartialReflect {
/// Returns an iterator over the values of the reflectable fields for this struct. /// Returns an iterator over the values of the reflectable fields for this struct.
fn iter_fields(&self) -> FieldIter; fn iter_fields(&self) -> FieldIter;
/// Creates a new [`DynamicStruct`] from this struct.
fn to_dynamic_struct(&self) -> DynamicStruct { fn to_dynamic_struct(&self) -> DynamicStruct {
let mut dynamic_struct = DynamicStruct::default(); let mut dynamic_struct = DynamicStruct::default();
dynamic_struct.set_represented_type(self.get_represented_type_info()); dynamic_struct.set_represented_type(self.get_represented_type_info());
@ -192,6 +193,7 @@ pub struct FieldIter<'a> {
} }
impl<'a> FieldIter<'a> { impl<'a> FieldIter<'a> {
/// Creates a new [`FieldIter`].
pub fn new(value: &'a dyn Struct) -> Self { pub fn new(value: &'a dyn Struct) -> Self {
FieldIter { FieldIter {
struct_val: value, struct_val: value,

View File

@ -76,6 +76,7 @@ pub struct TupleFieldIter<'a> {
} }
impl<'a> TupleFieldIter<'a> { impl<'a> TupleFieldIter<'a> {
/// Creates a new [`TupleFieldIter`].
pub fn new(value: &'a dyn Tuple) -> Self { pub fn new(value: &'a dyn Tuple) -> Self {
TupleFieldIter { TupleFieldIter {
tuple: value, tuple: value,

View File

@ -146,6 +146,7 @@ pub struct TupleStructFieldIter<'a> {
} }
impl<'a> TupleStructFieldIter<'a> { impl<'a> TupleStructFieldIter<'a> {
/// Creates a new [`TupleStructFieldIter`].
pub fn new(value: &'a dyn TupleStruct) -> Self { pub fn new(value: &'a dyn TupleStruct) -> Self {
TupleStructFieldIter { TupleStructFieldIter {
tuple_struct: value, tuple_struct: value,

View File

@ -169,7 +169,9 @@ pub enum TypeInfoError {
/// [kind]: ReflectKind /// [kind]: ReflectKind
#[error("kind mismatch: expected {expected:?}, received {received:?}")] #[error("kind mismatch: expected {expected:?}, received {received:?}")]
KindMismatch { KindMismatch {
/// Expected kind.
expected: ReflectKind, expected: ReflectKind,
/// Received kind.
received: ReflectKind, received: ReflectKind,
}, },
} }
@ -183,7 +185,7 @@ pub enum TypeInfoError {
/// 3. [`PartialReflect::get_represented_type_info`] /// 3. [`PartialReflect::get_represented_type_info`]
/// 4. [`TypeRegistry::get_type_info`] /// 4. [`TypeRegistry::get_type_info`]
/// ///
/// Each return a static reference to [`TypeInfo`], but they all have their own use cases. /// Each returns a static reference to [`TypeInfo`], but they all have their own use cases.
/// For example, if you know the type at compile time, [`Typed::type_info`] is probably /// For example, if you know the type at compile time, [`Typed::type_info`] is probably
/// the simplest. If you have a `dyn Reflect` you can use [`DynamicTyped::reflect_type_info`]. /// the simplest. If you have a `dyn Reflect` you can use [`DynamicTyped::reflect_type_info`].
/// If all you have is a `dyn PartialReflect`, you'll probably want [`PartialReflect::get_represented_type_info`]. /// If all you have is a `dyn PartialReflect`, you'll probably want [`PartialReflect::get_represented_type_info`].
@ -199,14 +201,40 @@ pub enum TypeInfoError {
/// [type path]: TypePath::type_path /// [type path]: TypePath::type_path
#[derive(Debug, Clone)] #[derive(Debug, Clone)]
pub enum TypeInfo { pub enum TypeInfo {
/// Type information for a [struct-like] type.
///
/// [struct-like]: crate::Struct
Struct(StructInfo), Struct(StructInfo),
/// Type information for a [tuple-struct-like] type.
///
/// [tuple-struct-like]: crate::TupleStruct
TupleStruct(TupleStructInfo), TupleStruct(TupleStructInfo),
/// Type information for a [tuple-like] type.
///
/// [tuple-like]: crate::Tuple
Tuple(TupleInfo), Tuple(TupleInfo),
/// Type information for a [list-like] type.
///
/// [list-like]: crate::List
List(ListInfo), List(ListInfo),
/// Type information for an [array-like] type.
///
/// [array-like]: crate::Array
Array(ArrayInfo), Array(ArrayInfo),
/// Type information for a [map-like] type.
///
/// [map-like]: crate::Map
Map(MapInfo), Map(MapInfo),
/// Type information for a [set-like] type.
///
/// [set-like]: crate::Set
Set(SetInfo), Set(SetInfo),
/// Type information for an [enum-like] type.
///
/// [enum-like]: crate::Enum
Enum(EnumInfo), Enum(EnumInfo),
/// Type information for an opaque type - see the [`OpaqueInfo`] docs for
/// a discussion of opaque types.
Opaque(OpaqueInfo), Opaque(OpaqueInfo),
} }
@ -557,6 +585,7 @@ pub struct OpaqueInfo {
} }
impl OpaqueInfo { impl OpaqueInfo {
/// Creates a new [`OpaqueInfo`].
pub fn new<T: Reflect + TypePath + ?Sized>() -> Self { pub fn new<T: Reflect + TypePath + ?Sized>() -> Self {
Self { Self {
ty: Type::of::<T>(), ty: Type::of::<T>(),

View File

@ -38,6 +38,7 @@ pub struct TypeRegistry {
/// A synchronized wrapper around a [`TypeRegistry`]. /// A synchronized wrapper around a [`TypeRegistry`].
#[derive(Clone, Default)] #[derive(Clone, Default)]
pub struct TypeRegistryArc { pub struct TypeRegistryArc {
/// The wrapped [`TypeRegistry`].
pub internal: Arc<RwLock<TypeRegistry>>, pub internal: Arc<RwLock<TypeRegistry>>,
} }
@ -313,6 +314,7 @@ impl TypeRegistry {
data.insert(D::from_type()); data.insert(D::from_type());
} }
/// Whether the type with given [`TypeId`] has been registered in this registry.
pub fn contains(&self, type_id: TypeId) -> bool { pub fn contains(&self, type_id: TypeId) -> bool {
self.registrations.contains_key(&type_id) self.registrations.contains_key(&type_id)
} }
@ -684,6 +686,7 @@ impl Clone for TypeRegistration {
/// ///
/// [crate-level documentation]: crate /// [crate-level documentation]: crate
pub trait TypeData: Downcast + Send + Sync { pub trait TypeData: Downcast + Send + Sync {
/// Creates a type-erased clone of this value.
fn clone_type_data(&self) -> Box<dyn TypeData>; fn clone_type_data(&self) -> Box<dyn TypeData>;
} }
impl_downcast!(TypeData); impl_downcast!(TypeData);
@ -702,6 +705,7 @@ where
/// This is used by the `#[derive(Reflect)]` macro to generate an implementation /// This is used by the `#[derive(Reflect)]` macro to generate an implementation
/// of [`TypeData`] to pass to [`TypeRegistration::insert`]. /// of [`TypeData`] to pass to [`TypeRegistration::insert`].
pub trait FromType<T> { pub trait FromType<T> {
/// Creates an instance of `Self` for type `T`.
fn from_type() -> Self; fn from_type() -> Self;
} }
@ -746,6 +750,8 @@ impl ReflectSerialize {
/// [`FromType::from_type`]. /// [`FromType::from_type`].
#[derive(Clone)] #[derive(Clone)]
pub struct ReflectDeserialize { pub struct ReflectDeserialize {
/// Function used by [`ReflectDeserialize::deserialize`] to
/// perform deserialization.
pub func: fn( pub func: fn(
deserializer: &mut dyn erased_serde::Deserializer, deserializer: &mut dyn erased_serde::Deserializer,
) -> Result<Box<dyn Reflect>, erased_serde::Error>, ) -> Result<Box<dyn Reflect>, erased_serde::Error>,

View File

@ -16,6 +16,7 @@ use core::{
/// ///
/// [`Non`]: NonGenericTypeCell /// [`Non`]: NonGenericTypeCell
pub trait TypedProperty: sealed::Sealed { pub trait TypedProperty: sealed::Sealed {
/// The type of the value stored in [`GenericTypeCell`].
type Stored: 'static; type Stored: 'static;
} }