You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@avro.apache.org by kr...@apache.org on 2026/01/18 21:40:56 UTC
(avro-rs) 01/05: fix(doc): Small improvements
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 <gi...@kriskras99.nl>
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> {