docs: Remove references to ItemKey::Unknown

Author: Serial-ATA

doc/NEW_TAG.md

@@ -351,12 +351,9 @@ impl SplitTag for FooTag {
 Now callers can split their `FooTag` into a generic `Tag`, but we'll need a way to merge them back together.
 This is done with the `MergeTag` trait.
 
-When implementing `MergeTag`, one must take two things into consideration:
-
-* The distinction between `ItemValue::Text` and `ItemValue::Locator` in certain formats
+When implementing `MergeTag`, one may need to take the distinction between `ItemValue::Text` and `ItemValue::Locator` into consideration.
   * In ID3v2 for example, a locator is only valid for frames starting with W.
   * In a format such as VorbisComments, there is no need to distinguish between the two.
-* The presence of `ItemKey::Unknown`
 
 With that in mind, we'll now implement `MergeTag` on `SplitTagRemainder`:
 

lofty/src/id3/v2/tag.rs

@@ -88,18 +88,18 @@ macro_rules! impl_accessor {
 ///
 /// 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. See [`CommentFrame`] and [`UnsynchronizedTextFrame`] respectively.
-/// An attempt is made to create this information, but it may be incorrect.
-///    * `language` - Unknown and set to "XXX"
-///    * `description` - Left empty, which is invalid if there are more than one of these frames. These frames can only be identified
+/// * [`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"
+///      * `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.
-/// * [`ItemKey::Unknown("WXXX" | "TXXX")`](ItemKey::Unknown) - These frames are also identified by their descriptions.
+///   * 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 the one for `ReplayGain`,
-/// otherwise [`ItemKey::Unknown`] will be used.
-/// * Frames that require a language (COMM/USLT) - With ID3v2 being the only format that allows for language-specific items, this information is not retained.
+/// * 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

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

@@ -37,14 +37,11 @@ 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.
 ///
 /// ### From `Tag`
 ///
-/// When converting a [`TagItem`], two conditions must be met:
-///
-/// * The [`TagItem`] has a value other than [`ItemValue::Binary`](crate::ItemValue::Binary)
-/// * It has a key that is 4 bytes in length and within the ASCII range
+/// When converting a [`TagItem`], it must have a value other than [`ItemValue::Binary`](crate::ItemValue::Binary)
 #[derive(Default, Debug, PartialEq, Eq, Clone)]
 #[tag(description = "A RIFF INFO LIST", supported_formats(Wav))]
 pub struct RiffInfoList {

lofty/src/ogg/tag.rs

@@ -52,9 +52,6 @@ macro_rules! impl_accessor {
 /// If a [`TagItem`] with the key [`ItemKey::EncoderSoftware`] is available, it will be taken and
 /// used for the vendor string.
 ///
-/// [`TagItem`]s with [`ItemKey::Unknown`] will have their keys verified for spec compliance. They must fall within
-/// ASCII range `0x20` through `0x7D`, excluding `0x3D` ('=').
-///
 /// 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`].

lofty/src/tag/mod.rs

@@ -363,8 +363,6 @@ impl Tag {
 	///
 	/// * This **will not** verify an [`ItemKey`] mapping exists
 	/// * This **will not** allow writing item keys that are out of spec (keys are verified before writing)
-	///
-	/// This is only necessary if dealing with [`ItemKey::Unknown`].
 	pub fn insert_unchecked(&mut self, item: TagItem) {
 		self.retain(|i| i.item_key != item.item_key);
 		self.items.push(item);
@@ -391,7 +389,7 @@ impl Tag {
 
 	/// Append a [`TagItem`] to the tag
 	///
-	/// Notes: See [`Tag::insert_unchecked`]
+	/// Notes: See [`Tag::push()`] and the notes of [`Tag::insert_unchecked()`]
 	pub fn push_unchecked(&mut self, item: TagItem) {
 		self.items.push(item);
 	}