From 2f5712140121950f2abe79e28e7c59bbfeb1e90b Mon Sep 17 00:00:00 2001 From: Dmitry Stepanov Date: Tue, 15 Apr 2025 20:22:28 +0300 Subject: [PATCH] finished visitor docs --- fyrox-core/src/visitor/error.rs | 9 ++++- fyrox-core/src/visitor/field.rs | 67 ++++++++++++++++++++++++++------- fyrox-core/src/visitor/mod.rs | 3 ++ fyrox-core/src/visitor/pod.rs | 3 ++ 4 files changed, 67 insertions(+), 15 deletions(-) diff --git a/fyrox-core/src/visitor/error.rs b/fyrox-core/src/visitor/error.rs index 795c81f4d..7a15e7666 100644 --- a/fyrox-core/src/visitor/error.rs +++ b/fyrox-core/src/visitor/error.rs @@ -18,6 +18,8 @@ // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +//! Possible errors that may occur during serialization/deserialization. + use crate::io::FileError; use base64::DecodeError; use std::num::{ParseFloatError, ParseIntError}; @@ -45,8 +47,9 @@ pub enum VisitError { /// Attempting to enter a region on a write-mode Visitor when a region already has the /// given name. RegionAlreadyExists(String), + /// Current node handle is invalid and does not lead to a real node. InvalidCurrentNode, - /// Attempting to visit a field using a read-mode Visitor when when that field was originally + /// Attempting to visit a field using a read-mode Visitor when that field was originally /// written using a value of a different type. FieldTypeDoesNotMatch, /// Attempting to enter a region on a read-mode Visitor when no region in the visitor's data @@ -75,9 +78,13 @@ pub enum VisitError { PoisonedMutex, /// A FileLoadError was encountered while trying to decode Visitor data from a file. FileLoadError(FileError), + /// Integer parsing error. ParseIntError(ParseIntError), + /// Floating point number parsing error. ParseFloatError(ParseFloatError), + /// An error occurred when trying to decode base64-encoded data. DecodeError(DecodeError), + /// An error occurred when trying to parse uuid from a string. UuidError(uuid::Error), } diff --git a/fyrox-core/src/visitor/field.rs b/fyrox-core/src/visitor/field.rs index c9f1cd1a6..734f7a881 100644 --- a/fyrox-core/src/visitor/field.rs +++ b/fyrox-core/src/visitor/field.rs @@ -18,6 +18,8 @@ // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +//! A set fundamental data types. + use nalgebra::{Matrix2, Matrix3, Matrix4, UnitComplex, UnitQuaternion, Vector2, Vector3, Vector4}; use uuid::Uuid; @@ -28,24 +30,40 @@ use uuid::Uuid; /// same type as the field. #[derive(PartialEq, Debug)] pub enum FieldKind { + /// Boolean value. Bool(bool), + /// `u8` value. U8(u8), + /// `i8` value. I8(i8), + /// `u16` value. U16(u16), + /// `i16` value. I16(i16), + /// `u32` value. U32(u32), + /// `i32` value. I32(i32), + /// `u64` value. U64(u64), + /// `i64` value. I64(i64), + /// `f32` value. F32(f32), + /// `f64` value. F64(f64), + /// Unit quaternion. UnitQuaternion(UnitQuaternion), + /// 4x4 f32 matrix. Matrix4(Matrix4), /// A representation of some `Vec` where `T` must be [Copy]. /// It is mostly used to store the bytes of string types. BinaryBlob(Vec), + /// 3x3 f32 matrix. Matrix3(Matrix3), + /// Unique id. Uuid(Uuid), + /// A complex number. UnitComplex(UnitComplex), /// A representation for arrays of [`crate::visitor::pod::Pod`] types as a `Vec`. PodArray { @@ -57,53 +75,73 @@ pub enum FieldKind { /// The bytes that store the data, with unspecified endianness. bytes: Vec, }, + /// 2x2 f32 matrix. Matrix2(Matrix2), - + /// 2D f32 vector. Vector2F32(Vector2), + /// 3D f32 vector. Vector3F32(Vector3), + /// 4D f32 vector. Vector4F32(Vector4), - + /// 2D f64 vector. Vector2F64(Vector2), + /// 3D f64 vector. Vector3F64(Vector3), + /// 4D f64 vector. Vector4F64(Vector4), - + /// 2D u8 vector. Vector2U8(Vector2), + /// 3D u8 vector. Vector3U8(Vector3), + /// 4D u8 vector. Vector4U8(Vector4), - + /// 2D i8 vector. Vector2I8(Vector2), + /// 3D i8 vector. Vector3I8(Vector3), + /// 4D i8 vector. Vector4I8(Vector4), - + /// 2D u16 vector. Vector2U16(Vector2), + /// 3D u16 vector. Vector3U16(Vector3), + /// 4D u16 vector. Vector4U16(Vector4), - + /// 2D i16 vector. Vector2I16(Vector2), + /// 3D i16 vector. Vector3I16(Vector3), + /// 4D i16 vector. Vector4I16(Vector4), - + /// 2D u32 vector. Vector2U32(Vector2), + /// 3D u32 vector. Vector3U32(Vector3), + /// 4D u32 vector. Vector4U32(Vector4), - + /// 2D i32 vector. Vector2I32(Vector2), + /// 3D i32 vector. Vector3I32(Vector3), + /// 4D i32 vector. Vector4I32(Vector4), - + /// 2D u64 vector. Vector2U64(Vector2), + /// 3D u64 vector. Vector3U64(Vector3), + /// 4D u64 vector. Vector4U64(Vector4), - + /// 2D i64 vector. Vector2I64(Vector2), + /// 3D i64 vector. Vector3I64(Vector3), + /// 4D i64 vector. Vector4I64(Vector4), } -/// Values within a visitor are constructed from Fields. -/// Each Field has a name and a value. The name is used as a key to access the value -/// within the visitor using the [`crate::Visit::visit`] method, so each field within a value -/// must have a unique name. +/// Values within a visitor are constructed from Fields. Each Field has a name and a value. The name +/// is used as a key to access the value within the visitor using the [`crate::Visit::visit`] method, +/// so each field within a value must have a unique name. #[derive(PartialEq, Debug)] pub struct Field { /// The key string that allows access to the field. @@ -113,6 +151,7 @@ pub struct Field { } impl Field { + /// Creates a new field from the given name and the given field kind. pub fn new(name: &str, kind: FieldKind) -> Self { Self { name: name.to_owned(), diff --git a/fyrox-core/src/visitor/mod.rs b/fyrox-core/src/visitor/mod.rs index dd21f99a2..e4e796f4d 100644 --- a/fyrox-core/src/visitor/mod.rs +++ b/fyrox-core/src/visitor/mod.rs @@ -35,6 +35,8 @@ //! //! See [`Visitor`] docs for more info. +#![warn(missing_docs)] + pub mod blackboard; pub mod error; pub mod field; @@ -90,6 +92,7 @@ pub struct BinaryBlob<'a, T> where T: Copy, { + /// A reference to a vector that represents a binary blob. pub vec: &'a mut Vec, } diff --git a/fyrox-core/src/visitor/pod.rs b/fyrox-core/src/visitor/pod.rs index 28340351e..e3ff2c654 100644 --- a/fyrox-core/src/visitor/pod.rs +++ b/fyrox-core/src/visitor/pod.rs @@ -18,6 +18,8 @@ // OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE // SOFTWARE. +//! Data types that can be serialized as-is, by dumping the memory into a file. + use crate::visitor::{ error::VisitError, field::{Field, FieldKind}, @@ -103,6 +105,7 @@ pub struct PodVecView<'a, T: Pod> { } impl<'a, T: Pod> PodVecView<'a, T> { + /// Creates a view from the given vector. pub fn from_pod_vec(vec: &'a mut Vec) -> Self { Self { type_id: T::type_id(),