This is an automated email from the ASF dual-hosted git repository. kriskras99 pushed a commit to branch feat/documentation in repository https://gitbox.apache.org/repos/asf/avro-rs.git
commit d17eb2742f69d16d6abf0f5ac97a9d777709ddb3 Author: Kriskras99 <[email protected]> AuthorDate: Sun Jan 18 10:15:08 2026 +0100 fix(doc): Small improvements --- avro/src/bytes.rs | 48 ++++++++++++++++++++++------------------ avro/src/schema/mod.rs | 17 ++++++++------ avro/src/schema_compatibility.rs | 2 +- avro/src/serde/de.rs | 2 +- avro/src/serde/ser.rs | 4 ++-- 5 files changed, 40 insertions(+), 33 deletions(-) diff --git a/avro/src/bytes.rs b/avro/src/bytes.rs index bac4e3f..34f836e 100644 --- a/avro/src/bytes.rs +++ b/avro/src/bytes.rs @@ -18,14 +18,14 @@ use std::cell::Cell; thread_local! { - /// A thread local that is used to decide how to serialize Rust bytes into an Avro - /// `types::Value` of type bytes. + /// A thread local that is used to decide if Rust bytes need to be serialized to + /// [`Value::Bytes`] or [`Value::Fixed`]. /// /// Relies on the fact that serde's serialization process is single-threaded. pub(crate) static SER_BYTES_TYPE: Cell<BytesType> = const { Cell::new(BytesType::Bytes) }; - /// A thread local that is used to decide how to deserialize an Avro `types::Value` - /// of type bytes into Rust bytes. + /// A thread local that is used to decide if a [`Value::Bytes`] needs to be deserialized to + /// a [`Vec`] or slice. /// /// Relies on the fact that serde's deserialization process is single-threaded. pub(crate) static DE_BYTES_BORROWED: Cell<bool> = const { Cell::new(false) }; @@ -40,7 +40,7 @@ pub(crate) enum BytesType { /// Efficient (de)serialization of Avro bytes values. /// /// This module is intended to be used through the Serde `with` attribute. Use -/// [`serde_avro_bytes_opt`](crate::serde_avro_bytes_opt) for optional bytes. +/// [`serde_avro_bytes_opt`] for optional bytes. /// /// See usage with below example: /// ```rust @@ -89,7 +89,7 @@ pub mod serde_avro_bytes { /// Efficient (de)serialization of optional Avro bytes values. /// /// This module is intended to be used through the Serde `with` attribute. Use -/// [`serde_avro_bytes`](crate::serde_avro_bytes) for non optional bytes. +/// [`serde_avro_bytes`] for non optional bytes. /// /// See usage with below example: /// ```rust @@ -142,7 +142,7 @@ pub mod serde_avro_bytes_opt { /// Efficient (de)serialization of Avro fixed values. /// /// This module is intended to be used through the Serde `with` attribute. Use -/// [`serde_avro_fixed_opt`](crate::serde_avro_fixed_opt) for optional fixed values. +/// [`serde_avro_fixed_opt`] for optional fixed values. /// /// See usage with below example: /// ```rust @@ -208,7 +208,7 @@ pub mod serde_avro_fixed { /// Efficient (de)serialization of optional Avro fixed values. /// /// This module is intended to be used through the Serde `with` attribute. Use -/// [`serde_avro_fixed`](crate::serde_avro_fixed) for non optional fixed values. +/// [`serde_avro_fixed`] for non optional fixed values. /// /// See usage with below example: /// ```rust @@ -274,13 +274,12 @@ pub mod serde_avro_fixed_opt { /// Efficient (de)serialization of Avro bytes/fixed borrowed values. /// -/// This module is intended to be used through the Serde `with` attribute. Note that -/// `bytes: &[u8]` are always serialized as -/// [`Value::Bytes`](crate::types::Value::Bytes). However, both -/// [`Value::Bytes`](crate::types::Value::Bytes) and -/// [`Value::Fixed`](crate::types::Value::Fixed) can be deserialized as `bytes: -/// &[u8]`. Use [`serde_avro_slice_opt`](crate::serde_avro_slice_opt) for optional -/// bytes/fixed borrowed values. +/// This module is intended to be used through the Serde `with` attribute. +/// +/// Note that `&[u8]` are always serialized as [`Value::Bytes`]. However, +/// both [`Value::Bytes`] and [`Value::Fixed`] can be deserialized as `&[u8]`. +/// +/// Use [`serde_avro_slice_opt`] for optional bytes/fixed borrowed values. /// /// See usage with below example: /// ```rust @@ -294,6 +293,9 @@ pub mod serde_avro_fixed_opt { /// slice_field: &'a [u8], /// } /// ``` +/// +/// [`Value::Bytes`]: crate::types::Value::Bytes +/// [`Value::Fixed`]: crate::types::Value::Fixed pub mod serde_avro_slice { use super::DE_BYTES_BORROWED; use serde::{Deserializer, Serializer}; @@ -328,13 +330,12 @@ pub mod serde_avro_slice { /// Efficient (de)serialization of optional Avro bytes/fixed borrowed values. /// -/// This module is intended to be used through the Serde `with` attribute. Note that -/// `bytes: &[u8]` are always serialized as -/// [`Value::Bytes`](crate::types::Value::Bytes). However, both -/// [`Value::Bytes`](crate::types::Value::Bytes) and -/// [`Value::Fixed`](crate::types::Value::Fixed) can be deserialized as `bytes: -/// &[u8]`. Use [`serde_avro_slice`](crate::serde_avro_slice) for non optional -/// bytes/fixed borrowed values. +/// This module is intended to be used through the Serde `with` attribute. +/// +/// Note that `&[u8]` are always serialized as [`Value::Bytes`]. However, +/// both [`Value::Bytes`] and [`Value::Fixed`] can be deserialized as `&[u8]`. +/// +/// Use [`serde_avro_slice`] for non-optional bytes/fixed borrowed values. /// /// See usage with below example: /// ```rust @@ -348,6 +349,9 @@ pub mod serde_avro_slice { /// slice_field: Option<&'a [u8]>, /// } /// ``` +/// +/// [`Value::Bytes`]: crate::types::Value::Bytes +/// [`Value::Fixed`]: crate::types::Value::Fixed pub mod serde_avro_slice_opt { use super::DE_BYTES_BORROWED; use serde::{Deserializer, Serializer}; diff --git a/avro/src/schema/mod.rs b/avro/src/schema/mod.rs index e56eab8..110d1d8 100644 --- a/avro/src/schema/mod.rs +++ b/avro/src/schema/mod.rs @@ -320,17 +320,19 @@ impl Name { } /// Return the fully qualified name needed for indexing or searching for the schema within a schema/schema env context. Puts the enclosing namespace into the name's namespace for clarity in schema/schema env parsing - /// ```ignore - /// use apache_avro::schema::Name; + /// ``` + /// # use apache_avro::{Error, schema::Name}; /// /// assert_eq!( - /// Name::new("some_name")?.fully_qualified_name(&Some("some_namespace".into())), - /// Name::new("some_namespace.some_name")? + /// Name::new("some_name")?.fully_qualified_name(&Some("some_namespace".into())), + /// Name::new("some_namespace.some_name")? /// ); /// assert_eq!( - /// Name::new("some_namespace.some_name")?.fully_qualified_name(&Some("other_namespace".into())), - /// Name::new("some_namespace.some_name")? + /// Name::new("some_namespace.some_name")?.fully_qualified_name(&Some("other_namespace".into())), + /// Name::new("some_namespace.some_name")? /// ); + /// + /// # Ok::<(), Error>(()) // This makes `?` work in doctests /// ``` pub fn fully_qualified_name(&self, enclosing_namespace: &Namespace) -> Name { Name { @@ -2443,7 +2445,8 @@ impl Serialize for RecordField { } /// Parses a **valid** avro schema into the Parsing Canonical Form. -/// https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas +/// +/// <https://avro.apache.org/docs/current/specification/#parsing-canonical-form-for-schemas> fn parsing_canonical_form(schema: &Value, defined_names: &mut HashSet<String>) -> String { match schema { Value::Object(map) => pcf_map(map, defined_names), diff --git a/avro/src/schema_compatibility.rs b/avro/src/schema_compatibility.rs index 74ae558..281a293 100644 --- a/avro/src/schema_compatibility.rs +++ b/avro/src/schema_compatibility.rs @@ -103,7 +103,7 @@ impl Checker { hasher.finish() } - /// The actual implementation of [`full_match_schemas`] but without the recursion protection. + /// The actual implementation of [`Self::full_match_schemas`] but without the recursion protection. /// /// This function should never be called directly as it can recurse infinitely on recursive types. #[rustfmt::skip] diff --git a/avro/src/serde/de.rs b/avro/src/serde/de.rs index ce42576..04c0f74 100644 --- a/avro/src/serde/de.rs +++ b/avro/src/serde/de.rs @@ -772,7 +772,7 @@ impl<'de> de::Deserializer<'de> for StringDeserializer { } } -/// Interpret a `Value` as an instance of type `D`. +/// Deserialize from a [`Value`]. /// /// This conversion can fail if the structure of the `Value` does not match the /// structure expected by `D`. diff --git a/avro/src/serde/ser.rs b/avro/src/serde/ser.rs index d78f501..3efbd62 100644 --- a/avro/src/serde/ser.rs +++ b/avro/src/serde/ser.rs @@ -476,13 +476,13 @@ impl ser::SerializeStructVariant for StructVariantSerializer<'_> { } } -/// Interpret a serializeable instance as a `Value`. +/// Serialize to a [`Value`]. /// /// This conversion can fail if the value is not valid as per the Avro specification. /// e.g: `HashMap` with non-string keys. /// /// This function does not work if `S` has any fields (recursively) that have the `#[serde(flatten)]` -/// attribute. Please use [`Writer::append_ser`] if that's the case. +/// attribute. Please use [`Writer::append_ser`] instead. /// /// [`Writer::append_ser`]: crate::Writer::append_ser pub fn to_value<S: Serialize>(value: S) -> Result<Value, Error> {
