docs: fixes, comments, and examples

Co-authored-by: Serial <69764315+serial-ata@users.noreply.github.com>

Author: thedavidweng

CHANGELOG.md

@@ -16,6 +16,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - **APE**: The `Tag` -> `ApeTag` conversion will now preserve multi-value items ([issue](https://github.com/Serial-ATA/lofty-rs/issues/631)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/633))
 
+### Removed
+
+- **ItemKey**: `ItemKey::FileType` and `ItemKey::MusicianCredits` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/636))
+    - These are ID3v2-specific fields with special formats.
+
 ## [0.23.3] - 2026-03-14
 
 ### Added

doc/ISSUES.md

@@ -97,7 +97,7 @@ The "[MISC] Feature Request" issue template is for feature requests that either:
 
 The "[API] Feature Request" issue template is for feature requests that have a specific design.
 
-If you have an feature with an exact idea of how it should be used, be sure to use this template.
+If you have a feature with an exact idea of how it should be used, be sure to use this template.
 
 The "API design" form should only serve as a design, not an implementation.
 

doc/NEW_FILE.md

@@ -57,7 +57,7 @@ Now that the directories are created, we can start working on defining our file.
 
 Before we can define the file struct, we need to add a variant to `FileType`.
 
-Go to [src/file.rs](../src/file.rs) and edit the `FileType` enum to add your new variant.
+Go to [src/file/file_type.rs](../lofty/src/file/file_type.rs) and edit the `FileType` enum to add your new variant.
 
 ```rust
 pub enum FileType {
@@ -216,7 +216,8 @@ They can be easily defined in a few lines:
 use std::io::Cursor;
 
 use libfuzzer_sys::fuzz_target;
-use lofty::{AudioFile, ParseOptions};
+use lofty::config::ParseOptions;
+use lofty::file::AudioFile;
 
 fuzz_target!(|data: Vec<u8>| {
     let _ = lofty::foo::FooFile::read_from(

doc/NEW_TAG.md

@@ -35,7 +35,7 @@ This document will cover the implementation of a tag file format named "Foo".
 To define a new tag format, first determine if it is supported by a single format. In this example it is,
 so we would place its definition in a subdirectory of the `foo` directory, where we defined the Foo audio format.
 If this was a generic tag format supported by multiple audio formats, like ID3, you'd simply define it in its own
-folder inside [src/](../src).
+folder inside [src/](../lofty/src).
 
 There are some files that every tag needs:
 
@@ -62,7 +62,7 @@ Now that the directories are created, we can start working on defining our file.
 
 Before we can define the tag struct, we need to add a variant to `TagType`.
 
-Go to [src/tag/mod.rs](../src/tag/mod.rs) and edit the `TagType` enum to add your new variant.
+Go to [src/tag/mod.rs](../lofty/src/tag/mod.rs) and edit the `TagType` enum to add your new variant.
 
 ```rust
 pub enum TagType {
@@ -149,7 +149,7 @@ impl Accessor for FooTag {
 
     fn artist(&self) -> Option<Cow<'_, str>> { /**/ }
     fn set_artist(&mut self, value: String) { /**/ }
-    fn remove_artist() { /**/ }
+    fn remove_artist(&mut self) { /**/ }
 
     fn album(&self) -> Option<Cow<'_, str>> { /**/ }
     fn set_album(&mut self, value: String) { /**/ }
@@ -187,8 +187,8 @@ impl FooTag {
         self.items.push((key, value))
     }
 
-    pub fn remove<'a>(&'a mut self, key: &str) -> impl Iterator<Item=String> + use<'a> {
-        self.items.retain(|(k, _)| !k.eq_ignore_ascii_case(&key));
+    pub fn remove(&mut self, key: &str) {
+        self.items.retain(|(k, _)| !k.eq_ignore_ascii_case(key));
     }
 }
 ```
@@ -240,7 +240,7 @@ Converting your concrete tag type into the generic `Tag` involves the following:
 
 ##### Defining Generic Mappings
 
-The `ItemKey` mappings are defined in [src/tag/item.rs](../src/tag/item.rs).
+The `ItemKey` mappings are defined in [src/tag/item.rs](../lofty/src/tag/item.rs).
 
 See the comments for the `gen_map!` macro, which explains its use in detail, and will be kept up to
 date with any future changes.
@@ -411,7 +411,7 @@ TODO
 
 #### Assets
 
-Test assets for tag formats are to be placed in [tests/tags/assets/](../tests/tags/assets).
+Test assets for tag formats are to be placed in [tests/tags/assets/](../lofty/tests/tags/assets).
 
 There should at least be one asset, which is a binary file containing the tag below:
 
@@ -444,12 +444,12 @@ There are at least 4 unit tests that should be created for every tag format:
   * Using `crate::tag::utils::test_utils::create_tag()`, verify that the converted tag is correct
 
 These tests should be placed in the tag's `read` module. If there are many tests, feel free to break them out
-into their own module (ex. See the [ID3v2 `tests` module](../src/id3/v2/tag)).
+into their own module (ex. See the [ID3v2 `tests` module](../lofty/src/id3/v2/tag)).
 
 For an example of these tests, see the [ApeTag tests](https://github.com/Serial-ATA/lofty-rs/blob/9c0ea926c690bc6338ba95aceccc4d93e2ee9826/src/ape/tag/mod.rs#L540-L656).
 
 #### Integration Tests
 
 Integration testing is not normally necessary for tag formats, as they are typically
 tested extensively through the module's unit tests. However, if one wants to create integration tests,
-they can be placed in [tests/tags/](../tests/tags).
+they can be placed in [tests/tags/](../lofty/tests/tags).

doc/PULL_REQUESTS.md

@@ -14,7 +14,7 @@
 Before you create a PR, we ask that you do the following:
 
 1. **If fixing a bug, make an issue first**: The issue tracker should have a searchable history of
-bugs reports.
+bug reports.
 
 2. **If adding a feature, make an issue or discussion first**: Features should be discussed prior to implementation.
 

lofty/src/file/file_type.rs

@@ -47,21 +47,33 @@ pub const EXTENSIONS: &[&str] = &[
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(PartialEq, Eq, Copy, Clone, Debug)]
 #[allow(clippy::unsafe_derive_deserialize)]
-#[allow(missing_docs)]
 #[non_exhaustive]
 pub enum FileType {
+	/// Advanced Audio Coding (AAC/ADTS)
 	Aac,
+	/// Audio Interchange File Format
 	Aiff,
+	/// Monkey's Audio
 	Ape,
+	/// Free Lossless Audio Codec
 	Flac,
+	/// MPEG-1/2 Audio (MP1, MP2, MP3)
 	Mpeg,
+	/// MPEG-4 Audio (M4A, M4B, etc.)
 	Mp4,
+	/// Musepack
 	Mpc,
+	/// Opus
 	Opus,
+	/// Ogg Vorbis
 	Vorbis,
+	/// Speex
 	Speex,
+	/// Waveform Audio
 	Wav,
+	/// WavPack
 	WavPack,
+	/// A custom file type, registered through [`register_custom_resolver`](crate::resolve::register_custom_resolver)
 	Custom(&'static str),
 }
 

lofty/src/id3/mod.rs

@@ -1,7 +1,9 @@
 //! ID3 specific items
 //!
-//! ID3 does things differently than other tags, making working with them a little more effort than other formats.
-//! Check the other modules for important notes and/or warnings.
+//! This covers both [`v1`] (ID3v1) and [`v2`] (ID3v2) tag formats.
+//!
+//! ID3 does things differently than other tags, making them a little more cumbersome to work with.
+//! Check the other modules for important notes and warnings.
 
 pub mod v1;
 pub mod v2;

lofty/src/id3/v2/frame/header/mod.rs

@@ -14,9 +14,9 @@ use std::fmt::{Display, Formatter};
 /// These are rarely constructed by hand. Usually they are created in the background
 /// when making a new [`Frame`](crate::id3::v2::Frame).
 #[derive(Clone, Debug, PartialEq, Eq, Hash)]
-#[allow(missing_docs)]
 pub struct FrameHeader<'a> {
 	pub(crate) id: FrameId<'a>,
+	/// The frame's flags
 	pub flags: FrameFlags,
 }
 

lofty/src/id3/v2/items/event_timing_codes_frame.rs

@@ -22,54 +22,93 @@ const FRAME_ID: FrameId<'static> = FrameId::Valid(Cow::Borrowed("ETCO"));
 /// >>> like setting off an explosion on-stage, activating a screensaver etc.
 #[repr(u8)]
 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Debug, Hash)]
-#[allow(missing_docs)]
 pub enum EventType {
+	/// Padding (has no meaning)
 	Padding = 0x00,
+	/// End of initial silence
 	EndOfInitialSilence = 0x01,
+	/// Intro start
 	IntroStart = 0x02,
+	/// Main part start
 	MainPartStart = 0x03,
+	/// Outro start
 	OutroStart = 0x04,
+	/// Outro end
 	OutroEnd = 0x05,
+	/// Verse start
 	VerseStart = 0x06,
+	/// Refrain start
 	RefrainStart = 0x07,
+	/// Interlude start
 	InterludeStart = 0x08,
+	/// Theme start
 	ThemeStart = 0x09,
+	/// Variation start
 	VariationStart = 0x0A,
+	/// Key change
 	KeyChange = 0x0B,
+	/// Time change
 	TimeChange = 0x0C,
+	/// Momentary unwanted noise (Alarm, Phone, etc.)
 	MomentaryUnwantedNoise = 0x0D,
+	/// Sustained noise
 	SustainedNoise = 0x0E,
+	/// Sustained noise end
 	SustainedNoiseEnd = 0x0F,
+	/// Intro end
 	IntroEnd = 0x10,
+	/// Main part end
 	MainPartEnd = 0x11,
+	/// Verse end
 	VerseEnd = 0x12,
+	/// Refrain end
 	RefrainEnd = 0x13,
+	/// Theme end
 	ThemeEnd = 0x14,
+	/// Profanity
 	Profanity = 0x15,
+	/// Profanity end
 	ProfanityEnd = 0x16,
 
-	// User-defined events
+	/// Not predefined synch 0 (user event)
 	NotPredefinedSynch0 = 0xE0,
+	/// Not predefined synch 1 (user event)
 	NotPredefinedSynch1 = 0xE1,
+	/// Not predefined synch 2 (user event)
 	NotPredefinedSynch2 = 0xE2,
+	/// Not predefined synch 3 (user event)
 	NotPredefinedSynch3 = 0xE3,
+	/// Not predefined synch 4 (user event)
 	NotPredefinedSynch4 = 0xE4,
+	/// Not predefined synch 5 (user event)
 	NotPredefinedSynch5 = 0xE5,
+	/// Not predefined synch 6 (user event)
 	NotPredefinedSynch6 = 0xE6,
+	/// Not predefined synch 7 (user event)
 	NotPredefinedSynch7 = 0xE7,
+	/// Not predefined synch 8 (user event)
 	NotPredefinedSynch8 = 0xE8,
+	/// Not predefined synch 9 (user event)
 	NotPredefinedSynch9 = 0xE9,
+	/// Not predefined synch A (user event)
 	NotPredefinedSynchA = 0xEA,
+	/// Not predefined synch B (user event)
 	NotPredefinedSynchB = 0xEB,
+	/// Not predefined synch C (user event)
 	NotPredefinedSynchC = 0xEC,
+	/// Not predefined synch D (user event)
 	NotPredefinedSynchD = 0xED,
+	/// Not predefined synch E (user event)
 	NotPredefinedSynchE = 0xEE,
+	/// Not predefined synch F (user event)
 	NotPredefinedSynchF = 0xEF,
 
+	/// Audio end (start of silence)
 	AudioEnd = 0xFD,
+	/// Audio file ends
 	AudioFileEnds = 0xFE,
 
-	/// 0x17..=0xDF and 0xF0..=0xFC
+	/// Reserved event type (0x17..=0xDF and 0xF0..=0xFC)
 	Reserved,
 }
 

lofty/src/id3/v2/items/relative_volume_adjustment_frame.rs

@@ -16,16 +16,24 @@ const FRAME_ID: FrameId<'static> = FrameId::Valid(Cow::Borrowed("RVA2"));
 /// A channel identifier used in the RVA2 frame
 #[repr(u8)]
 #[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Debug, Hash)]
-#[allow(missing_docs)]
 pub enum ChannelType {
+	/// Other channel type
 	Other = 0,
+	/// Master volume
 	MasterVolume = 1,
+	/// Front right
 	FrontRight = 2,
+	/// Front left
 	FrontLeft = 3,
+	/// Back right
 	BackRight = 4,
+	/// Back left
 	BackLeft = 5,
+	/// Front centre
 	FrontCentre = 6,
+	/// Back centre
 	BackCentre = 7,
+	/// Subwoofer
 	Subwoofer = 8,
 }