docs: Improve tag conversion docs

Author: Serial-ATA

lofty/src/ape/tag/mod.rs

@@ -61,8 +61,7 @@ macro_rules! impl_accessor {
 /// a normal [`ItemValue`](crate::tag::ItemValue) unlike other formats.
 ///
 /// Pictures are stored as [`ItemValue::Binary`](crate::tag::ItemValue::Binary), and can be converted with
-/// [`Picture::from_ape_bytes`](crate::picture::Picture::from_ape_bytes). For the appropriate item keys, see
-/// [`APE_PICTURE_TYPES`](crate::ape::APE_PICTURE_TYPES).
+/// [`Picture::from_ape_bytes()`]. For the appropriate item keys, see [`APE_PICTURE_TYPES`].
 ///
 /// ## Conversions
 ///
@@ -72,8 +71,20 @@ macro_rules! impl_accessor {
 ///
 /// ### From `Tag`
 ///
+/// Converting [`Tag`]s into `ApeTag` is *mostly* seamless.
+///
+/// #### Items
+///
+/// As long at the [`ItemKey`] has a mapping for APE, it can be converted to an [`ApeItem`].
+///
+/// #### Pictures
+///
 /// When converting pictures, any of type [`PictureType::Undefined`](crate::picture::PictureType::Undefined) will be discarded.
-/// For items, see [`ApeItem::new`].
+/// Since APE doesn't have dedicated item types for pictures like other formats (e.g. [Id3v2Tag]), pictures
+/// **must** be disambiguated by their [`PictureType`](crate::picture::PictureType).
+///
+/// [`Picture::from_ape_bytes()`]: crate::picture::Picture::from_ape_bytes
+/// [`APE_PICTURE_TYPES`]: crate::ape::APE_PICTURE_TYPES
 #[derive(Default, Debug, PartialEq, Eq, Clone)]
 #[tag(
 	description = "An `APE` tag",

lofty/src/id3/v1/tag.rs

@@ -56,19 +56,24 @@ macro_rules! impl_accessor {
 /// * `comment` -> [`ItemKey::Comment`]
 /// * `track_number` -> [`ItemKey::TrackNumber`]
 /// * `genre` -> [`ItemKey::Genre`] (As long as the genre is a valid index into [`GENRES`])
-///
+/// 	* Note that [`ItemKey::Genre`] will contain the *string* at [`GENRES`]\[index\], not the index.
 ///
 /// ### From `Tag`
 ///
+/// #### Items
+///
 /// All of the [`ItemKey`]s referenced in the conversion to [`Tag`] will be checked.
 ///
 /// The values will be used as-is, with two exceptions:
 ///
 /// * [`ItemKey::TrackNumber`] - Will only be used if the value can be parsed as a `u8`
 /// * [`ItemKey::Genre`] - Will only be used if:
+/// 	* [`GENRES`] contains the string
+/// 	* **OR** The [`ItemValue`](crate::ItemValue) can be parsed into a `u8` ***and*** it is a valid index into [`GENRES`]
+///
+/// #### Pictures
 ///
-/// 	[`GENRES`] contains the string **OR** The [`ItemValue`](crate::ItemValue) can be parsed into
-/// 	a `u8` ***and*** it is a valid index into [`GENRES`]
+/// Pictures will be discarded, as they aren't supported in this format.
 #[derive(Default, Debug, PartialEq, Eq, Clone)]
 #[tag(
 	description = "An ID3v1 tag",

lofty/src/id3/v2/tag.rs

@@ -76,35 +76,33 @@ macro_rules! impl_accessor {
 ///
 /// In the [`Accessor`] methods, these values have the separators (`\0`) replaced with `"/"` for convenience.
 ///
+/// ## Special Frames
+///
+/// ID3v2 has `GEOB` and `SYLT` frames, which are not parsed by default, instead storing them as [`FrameType::Binary`].
+/// They can easily be parsed with [`GeneralEncapsulatedObject::parse`](crate::id3::v2::GeneralEncapsulatedObject::parse)
+/// and [`SynchronizedText::parse`](crate::id3::v2::SynchronizedTextFrame::parse) respectively, and converted back to binary with
+/// [`GeneralEncapsulatedObject::as_bytes`](crate::id3::v2::GeneralEncapsulatedObject::as_bytes) and
+/// [`SynchronizedText::as_bytes`](crate::id3::v2::SynchronizedTextFrame::as_bytes) for writing.
+///
 /// ## Conversions
 ///
-/// ⚠ **Warnings** ⚠
+/// ### To `Tag`
+///
+/// * TXXX/WXXX
+/// 	* These frames map to [`ItemKey`] by their description, rather than their frame ID (e.g. `TXXX:REPLAYGAIN_ALBUM_GAIN` maps to [`ItemKey::ReplayGainAlbumGain`]).
+///     * Anything without a mapping will be discarded.
+/// * POPM - These frames will be stored as a raw [`ItemValue::Binary`] value under the [`ItemKey::Popularimeter`] key.
 ///
 /// ### From `Tag`
 ///
 /// When converting from a [`Tag`] to an `Id3v2Tag`, some frames may need editing.
 ///
 /// * [`ItemKey::Comment`] and [`ItemKey::Lyrics`] - Unlike a normal text frame, these require a language and description.
 ///   * If these values aren't specified in the [`TagItem`], it will be filled in with (possibly incorrect) defaults.
-///      * `language` - Unknown and set to "XXX"
+///      * `language` - Set to [`UNKNOWN_LANGUAGE`]
 ///      * `description` - Left empty, which is invalid if there are more than one of these frames. These frames can only be identified
 ///    by their descriptions, and as such they are expected to be unique for each.
 ///   * See [`CommentFrame`] and [`UnsynchronizedTextFrame`] respectively.
-///
-/// ### To `Tag`
-///
-/// * TXXX/WXXX - These frames will be stored as an [`ItemKey`] by their description. Some variants exist
-///   for these descriptions, such as [`ItemKey::ReplayGainAlbumGain`]. Anything without a mapping will
-///   be discarded.
-/// * POPM - These frames will be stored as a raw [`ItemValue::Binary`] value under the [`ItemKey::Popularimeter`] key.
-///
-/// ## Special Frames
-///
-/// ID3v2 has `GEOB` and `SYLT` frames, which are not parsed by default, instead storing them as [`FrameType::Binary`].
-/// They can easily be parsed with [`GeneralEncapsulatedObject::parse`](crate::id3::v2::GeneralEncapsulatedObject::parse)
-/// and [`SynchronizedText::parse`](crate::id3::v2::SynchronizedTextFrame::parse) respectively, and converted back to binary with
-/// [`GeneralEncapsulatedObject::as_bytes`](crate::id3::v2::GeneralEncapsulatedObject::as_bytes) and
-/// [`SynchronizedText::as_bytes`](crate::id3::v2::SynchronizedTextFrame::as_bytes) for writing.
 #[derive(PartialEq, Eq, Debug, Clone)]
 #[tag(
 	description = "An `ID3v2` tag",

lofty/src/iff/wav/tag/mod.rs

@@ -43,7 +43,16 @@ macro_rules! impl_accessor {
 ///
 /// ### From `Tag`
 ///
-/// When converting a [`TagItem`], it must have a value other than [`ItemValue::Binary`](crate::ItemValue::Binary)
+/// #### Items
+///
+/// When converting a [`TagItem`], the only conditions are that:
+///
+/// * It has an [`ItemKey`] mapping
+/// * It has a value of [`ItemValue::Text`](crate::ItemValue::Text) or [`ItemValue::Locator`](crate::ItemValue::Locator)
+///
+/// #### Pictures
+///
+/// Pictures will be discarded, as they aren't supported in this format.
 #[derive(Default, Debug, PartialEq, Eq, Clone)]
 #[tag(description = "A RIFF INFO LIST", supported_formats(Wav))]
 pub struct RiffInfoList {

lofty/src/mp4/ilst/mod.rs

@@ -101,17 +101,25 @@ macro_rules! impl_flag_accessors {
 ///
 /// ### To `Tag`
 ///
-/// When converting to [`Tag`], only atoms with a value of [`AtomData::UTF8`] and [`AtomData::UTF16`],
-/// with the exception of the `trkn` and `disk` atoms, as well as pictures, will be preserved.
+/// For an [`Atom`] to be converted it must:
 ///
-/// Do note, all pictures will be [`PictureType::Other`](crate::PictureType::Other)
+/// * Have a value of [`AtomData::UTF8`] and [`AtomData::UTF16`]
+/// * **OR** be a `trkn`/`disk` atom
+/// * **OR** be a `covr` atom
+///
+/// Note that all pictures will be [`PictureType::Other`].
 ///
 /// ### From `Tag`
 ///
-/// When converting from [`Tag`], only items with a value of [`ItemValue::Text`](crate::ItemValue::Text), as
-/// well as pictures, will be preserved.
+/// #### Items
+///
+/// For a [`TagItem`] to be converted, it must have a value of [`ItemValue::Text`].
+///
+/// An attempt will be made to create the `TrackNumber/TrackTotal` (trkn) and `DiscNumber/DiscTotal` (disk) atoms.
+///
+/// #### Pictures
 ///
-/// An attempt will be made to create the `TrackNumber/TrackTotal` (trkn) and `DiscNumber/DiscTotal` (disk) pairs.
+/// [`Picture`]s will also be preserved, but their [`PictureType`] will be overwritten with [`PictureType::Other`].
 #[derive(Default, PartialEq, Debug, Clone)]
 #[tag(description = "An MP4 ilst atom", supported_formats(Mp4))]
 pub struct Ilst {

lofty/src/ogg/tag.rs

@@ -44,17 +44,26 @@ macro_rules! impl_accessor {
 ///
 /// ### To `Tag`
 ///
-/// All items will be converted to a [`TagItem`], with all unknown keys being stored with [`ItemKey::Unknown`].
+/// All items without an [`ItemKey`] mapping will be discarded.
 ///
 /// In order to preserve the vendor string, a required part of the OGG formats, it will simply be inserted as
 /// [`ItemKey::EncoderSoftware`], given an item with this key does not already exist.
 ///
 /// ### From `Tag`
 ///
+/// #### Items
+///
+/// When converting a [`TagItem`], the only conditions are that:
+///
+/// * It has an [`ItemKey`] mapping
+/// * It has a value of [`ItemValue::Text`] or [`ItemValue::Locator`]
+///
 /// If a [`TagItem`] with the key [`ItemKey::EncoderSoftware`] is available, it will be taken and
 /// used for the vendor string.
 ///
-/// When converting [Picture]s, they will first be passed through [`PictureInformation::from_picture`].
+/// #### Pictures
+///
+/// When converting [`Picture`]s, they will first be passed through [`PictureInformation::from_picture()`].
 /// If the information is available, it will be used. Otherwise, the picture will be stored with zeroed out
 /// [`PictureInformation`].
 #[derive(Default, PartialEq, Eq, Debug, Clone)]