From f62a978b559abc6b21389fd5148b9c50413777da Mon Sep 17 00:00:00 2001 From: open-schnick Date: Sat, 25 Oct 2025 12:02:15 -0400 Subject: [PATCH] Accessor: Document lack of multi-value support Co-authored-by: Serial <69764315+Serial-ATA@users.noreply.github.com> Signed-off-by: Serial <69764315+Serial-ATA@users.noreply.github.com> --- lofty/src/tag/accessor.rs | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/lofty/src/tag/accessor.rs b/lofty/src/tag/accessor.rs index fc32657ba..9fed93235 100644 --- a/lofty/src/tag/accessor.rs +++ b/lofty/src/tag/accessor.rs @@ -1,5 +1,8 @@ use std::borrow::Cow; +#[cfg(doc)] +use crate::{ogg::tag::VorbisComments, tag::Tag}; + // This defines the `Accessor` trait, used to define unified getters/setters for commonly // accessed tag values. // @@ -26,6 +29,10 @@ macro_rules! accessor_trait { /// /// This attempts to only provide methods for items that all tags have in common, /// but there may be exceptions. + /// + /// Note that for tag formats supporting multiple values, the behavior of any setter methods is + /// to **overwrite**, not append. If multi-value support is needed, consider using the format-specific methods. + /// For example: [`Tag::push()`] or [`VorbisComments::push()`]. pub trait Accessor { $( accessor_trait! { @GETTER [$($name)+] $($ty),+ } @@ -53,7 +60,13 @@ macro_rules! accessor_trait { }; (@GET_METHOD [$name:tt $($other:tt)*] Option<$ret_ty:ty>) => { paste::paste! { - #[doc = "Returns the " $name $(" " $other)*] + #[doc = "Returns the " $name $(" " $other)* "."] + /// + /// For formats that support multiple definitions of the same item, this will only return the first occurrence. + /// + /// To retrieve all occurrences of a given item, consider using the format-specific methods. + /// For example: [`Tag::get_items()`] or [`VorbisComments::get_all()`]. + /// /// # Example /// /// ```rust @@ -70,7 +83,14 @@ macro_rules! accessor_trait { }; (@SET_METHOD [$name:tt $($other:tt)*] $owned_ty:ty) => { paste::paste! { - #[doc = "Sets the " $name $(" " $other)*] + #[doc = "Sets the " $name $(" " $other)* "."] + /// + /// For formats that support multiple definitions of the same item, this will remove **all** + /// existing values, and replace them with `value`. + /// + /// To define multiple values, consider using the format-specific methods. + /// For example: [`Tag::push()`] or [`VorbisComments::push()`]. + /// /// # Example /// /// ```rust,ignore