docs: rewrite and clarify decoder documentation and API comments

- Improve clarity and conciseness of doc comments for all decoders
- Remove redundant and overly verbose explanations
- Add missing details to trait and method docs
- Update examples to use consistent file paths and types
- Move Settings struct visibility to crate-internal
- Refactor Path/PathBuf decoder constructors for optimal hinting
- Standardize iterator and trait method documentation across formats
- Remove misleading or outdated implementation notes
- Fix Zero source bits_per_sample to return None
- Update seek test attributes for feature consistency

Author: roderickvd

src/decoder/builder.rs

@@ -6,7 +6,7 @@
 //!
 //! # Features
 //!
-//! - **Bit depths**: Full support for 8, 16, 24, and 32-bit audio (including 12 and 20-bit)
+//! - **Bit depths**: Full support for 8, 12, 16, 20, 24, and 32-bit audio
 //! - **Sample rates**: Supports all FLAC-compatible sample rates (1Hz to 655,350Hz)
 //! - **Channels**: Supports mono, stereo, and multi-channel audio (up to 8 channels)
 //! - **Seeking**: Full forward and backward seeking with sample-accurate positioning
@@ -80,7 +80,7 @@ use crate::{
 
 /// Reader options for `claxon` FLAC decoder.
 ///
-/// Configured to skip metadata parsing and vorbis comments for faster initialization.
+/// Configured to skip metadata parsing and Vorbis comments for faster initialization.
 /// This improves decoder creation performance by only parsing essential stream information
 /// needed for audio playback.
 ///
@@ -139,7 +139,7 @@ where
     ///
     /// Used for calculating the correct memory layout when accessing interleaved samples.
     /// FLAC blocks can have variable sizes, so this changes per block.
-    current_block_channel_len: usize,
+    current_block_samples_per_channel: usize,
 
     /// Current position within the current block.
     ///
@@ -297,7 +297,7 @@ where
         Ok(Self {
             reader: Some(reader),
             current_block: Vec::with_capacity(max_block_size),
-            current_block_channel_len: 1,
+            current_block_samples_per_channel: 1,
             current_block_off: 0,
             bits_per_sample: spec.bits_per_sample,
             sample_rate: SampleRate::new(sample_rate)
@@ -350,15 +350,10 @@ where
 {
     /// Returns the number of samples before parameters change.
     ///
-    /// For FLAC, this always returns `None` because audio parameters (sample rate, channels, bit
-    /// depth) never change during the stream. This allows Rodio to optimize by not frequently
-    /// checking for parameter changes.
-    ///
-    /// # Implementation Note
+    /// # Returns
     ///
-    /// FLAC streams have fixed parameters throughout their duration, unlike some formats
-    /// that may have parameter changes at specific points. This enables optimizations
-    /// in the audio pipeline by avoiding frequent parameter validation.
+    /// For FLAC, this always returns `None` because audio parameters (sample rate, channels, bit
+    /// depth) never change during the stream.
     #[inline]
     fn current_span_len(&self) -> Option<usize> {
         None
@@ -374,26 +369,17 @@ where
     ///
     /// # Guarantees
     ///
-    /// The returned value is constant for the lifetime of the decoder and matches
-    /// the channel count specified in the FLAC stream metadata.
+    /// The returned value is constant for the lifetime of the decoder.
     #[inline]
     fn channels(&self) -> ChannelCount {
         self.channels
     }
 
     /// Returns the sample rate in Hz.
     ///
-    /// Common rates that FLAC supports are:
-    /// - **44.1kHz**: CD quality (most common)
-    /// - **48kHz**: Professional audio standard
-    /// - **96kHz**: High-resolution audio
-    /// - **192kHz**: Ultra high-resolution audio
-    ///
     /// # Guarantees
     ///
-    /// The returned value is constant for the lifetime of the decoder and matches
-    /// the sample rate specified in the FLAC stream metadata. This value is
-    /// available immediately upon decoder creation.
+    /// The returned value is constant for the lifetime of the decoder.
     #[inline]
     fn sample_rate(&self) -> SampleRate {
         self.sample_rate
@@ -404,32 +390,24 @@ where
     /// FLAC metadata contains the total number of samples, allowing accurate duration calculation.
     /// This is available immediately upon decoder creation without needing to scan the entire file.
     ///
-    /// Returns `None` only for malformed FLAC files missing sample count metadata.
-    ///
-    /// # Accuracy
+    /// # Returns
     ///
-    /// The duration is calculated from exact sample counts, providing sample-accurate
-    /// timing information. This is more precise than duration estimates based on
-    /// bitrate calculations used by lossy formats.
+    /// Returns `None` only for malformed FLAC files missing sample count metadata.
     #[inline]
     fn total_duration(&self) -> Option<Duration> {
         self.total_duration
     }
 
     /// Returns the bit depth of the audio samples.
     ///
-    /// FLAC is a lossless format that preserves the original bit depth:
-    /// - 16-bit: Standard CD quality
-    /// - 24-bit: Professional/high-resolution audio
-    /// - 32-bit: Professional/studio quality
-    /// - Other depths: 8, 12, and 20-bit are also supported
-    ///
-    /// Always returns `Some(depth)` for valid FLAC streams.
-    ///
     /// # Implementation Note
     ///
-    /// The bit depth information is preserved from the original FLAC stream and
+    /// Up to 24 bits of information is preserved from the original FLAC stream and
     /// used for proper sample scaling during conversion to Rodio's sample format.
+    ///
+    /// # Returns
+    ///
+    /// Always returns `Some(depth)` for valid FLAC streams.
     #[inline]
     fn bits_per_sample(&self) -> Option<u32> {
         Some(self.bits_per_sample)
@@ -476,12 +454,6 @@ where
     /// // Seek to 30 seconds into the track
     /// decoder.try_seek(Duration::from_secs(30)).unwrap();
     /// ```
-    ///
-    /// # Implementation Details
-    ///
-    /// The seeking implementation handles channel alignment to ensure that seeking
-    /// to a specific time position results in the correct channel being returned
-    /// for the first sample after the seek operation.
     fn try_seek(&mut self, pos: Duration) -> Result<(), SeekError> {
         // Seeking should be "saturating", meaning: target positions beyond the end of the stream
         // are clamped to the end.
@@ -545,9 +517,9 @@ impl<R> Iterator for FlacDecoder<R>
 where
     R: Read + Seek,
 {
-    /// The type of items yielded by the iterator.
+    /// The type of samples yielded by the iterator.
     ///
-    /// Returns `Sample` (typically `f32`) values representing individual audio samples.
+    /// Returns `Sample` values representing individual audio samples.
     /// Samples are interleaved across channels in the order: channel 0, channel 1, etc.
     type Item = Sample;
 
@@ -587,7 +559,7 @@ where
             if self.current_block_off < self.current_block.len() {
                 // Read from current block.
                 let real_offset = (self.current_block_off % self.channels.get() as usize)
-                    * self.current_block_channel_len
+                    * self.current_block_samples_per_channel
                     + self.current_block_off / self.channels.get() as usize;
                 let raw_val = self.current_block[real_offset];
                 self.current_block_off += 1;
@@ -622,7 +594,8 @@ where
                 .read_next_or_eof(buffer)
             {
                 Ok(Some(block)) => {
-                    self.current_block_channel_len = (block.len() / block.channels()) as usize;
+                    self.current_block_samples_per_channel =
+                        (block.len() / block.channels()) as usize;
                     self.current_block = block.into_buffer();
                 }
                 Ok(None) | Err(_) => {
@@ -634,7 +607,7 @@ where
         }
     }
 
-    /// Returns bounds on the remaining length of the iterator.
+    /// Returns bounds on the remaining amount of samples.
     ///
     /// Provides accurate size estimates based on FLAC metadata when available.
     /// This information can be used by consumers for buffer pre-allocation

src/decoder/flac.rs

@@ -63,7 +63,8 @@ use crate::{
 };
 
 pub mod builder;
-pub use builder::{DecoderBuilder, Settings};
+pub use builder::DecoderBuilder;
+use builder::Settings;
 
 mod utils;
 
@@ -148,6 +149,7 @@ enum DecoderImpl<R: Read + Seek> {
 enum Unreachable {}
 
 impl<R: Read + Seek> DecoderImpl<R> {
+    /// Advances the decoder and returns the next sample.
     #[inline]
     fn next(&mut self) -> Option<Sample> {
         match self {
@@ -165,6 +167,7 @@ impl<R: Read + Seek> DecoderImpl<R> {
         }
     }
 
+    /// Returns the bounds on the remaining amount of samples.
     #[inline]
     fn size_hint(&self) -> (usize, Option<usize>) {
         match self {
@@ -182,6 +185,7 @@ impl<R: Read + Seek> DecoderImpl<R> {
         }
     }
 
+    /// Returns the number of samples before the current span ends.
     #[inline]
     fn current_span_len(&self) -> Option<usize> {
         match self {
@@ -199,6 +203,7 @@ impl<R: Read + Seek> DecoderImpl<R> {
         }
     }
 
+    /// Returns the number of audio channels.
     #[inline]
     fn channels(&self) -> ChannelCount {
         match self {
@@ -216,6 +221,7 @@ impl<R: Read + Seek> DecoderImpl<R> {
         }
     }
 
+    /// Returns the sample rate in Hz.
     #[inline]
     fn sample_rate(&self) -> SampleRate {
         match self {
@@ -258,7 +264,10 @@ impl<R: Read + Seek> DecoderImpl<R> {
 
     /// Returns the bits per sample of this audio source.
     ///
-    /// For lossy formats this should always return `None`.
+    /// # Format Support
+    ///
+    /// For lossy formats this should always return `None` as bit depth is not a meaningful
+    /// concept for compressed audio.
     #[inline]
     fn bits_per_sample(&self) -> Option<u32> {
         match self {
@@ -276,6 +285,7 @@ impl<R: Read + Seek> DecoderImpl<R> {
         }
     }
 
+    /// Attempts to seek to a given position in the current source.
     #[inline]
     fn try_seek(&mut self, pos: Duration) -> Result<(), SeekError> {
         match self {
@@ -554,7 +564,7 @@ impl TryFrom<bytes::Bytes> for Decoder<std::io::Cursor<bytes::Bytes>> {
 /// use rodio::Decoder;
 ///
 /// // Embedded audio data (e.g., from include_bytes!)
-/// static AUDIO_DATA: &[u8] = include_bytes!("music.wav");
+/// static AUDIO_DATA: &[u8] = include_bytes!("../../assets/music.wav");
 /// let decoder = Decoder::try_from(AUDIO_DATA).unwrap();
 /// ```
 impl TryFrom<&'static [u8]> for Decoder<std::io::Cursor<&'static [u8]>> {
@@ -587,7 +597,7 @@ impl TryFrom<&'static [u8]> for Decoder<std::io::Cursor<&'static [u8]>> {
 ///     Decoder::try_from(data)
 /// }
 ///
-/// static EMBEDDED: &[u8] = include_bytes!("music.wav");
+/// static EMBEDDED: &[u8] = include_bytes!("../../assets/music.wav");
 /// let decoder1 = decode_audio(Cow::Borrowed(EMBEDDED)).unwrap();
 /// let owned_data = std::fs::read("music.wav").unwrap();
 /// let decoder2 = decode_audio(Cow::Owned(owned_data)).unwrap();
@@ -602,11 +612,11 @@ impl TryFrom<std::borrow::Cow<'static, [u8]>>
     }
 }
 
-/// Converts a `PathBuf` into a `Decoder`.
+/// Converts a `&Path` into a `Decoder`.
 ///
 /// This is a convenience method for loading audio files from filesystem paths. The file is opened
-/// and automatically configured with optimal settings including file size detection and seeking
-/// support.
+/// and automatically configured with optimal settings including file size detection, seeking
+/// support and format hint.
 ///
 /// # Errors
 ///
@@ -618,25 +628,24 @@ impl TryFrom<std::borrow::Cow<'static, [u8]>>
 /// # Examples
 /// ```no_run
 /// use rodio::Decoder;
-/// use std::path::PathBuf;
+/// use std::path::Path;
 ///
-/// let path = PathBuf::from("music.mp3");
+/// let path = Path::new("music.mp3");
 /// let decoder = Decoder::try_from(path).unwrap();
 /// ```
-impl TryFrom<std::path::PathBuf> for Decoder<BufReader<std::fs::File>> {
+impl TryFrom<&std::path::Path> for Decoder<BufReader<std::fs::File>> {
     type Error = DecoderError;
 
-    fn try_from(path: std::path::PathBuf) -> Result<Self, Self::Error> {
-        let file = std::fs::File::open(path).map_err(|e| Self::Error::IoError(e.to_string()))?;
-        Self::try_from(file)
+    fn try_from(path: &std::path::Path) -> Result<Self, Self::Error> {
+        path.to_path_buf().try_into()
     }
 }
 
-/// Converts a `&Path` into a `Decoder`.
+/// Converts a `PathBuf` into a `Decoder`.
 ///
 /// This is a convenience method for loading audio files from filesystem paths. The file is opened
-/// and automatically configured with optimal settings including file size detection and seeking
-/// support.
+/// and automatically configured with optimal settings including file size detection, seeking
+/// support and format hint.
 ///
 /// # Errors
 ///
@@ -648,52 +657,43 @@ impl TryFrom<std::path::PathBuf> for Decoder<BufReader<std::fs::File>> {
 /// # Examples
 /// ```no_run
 /// use rodio::Decoder;
-/// use std::path::Path;
+/// use std::path::PathBuf;
 ///
-/// let path = Path::new("music.mp3");
+/// let path = PathBuf::from("music.mp3");
 /// let decoder = Decoder::try_from(path).unwrap();
 /// ```
-impl TryFrom<&std::path::Path> for Decoder<BufReader<std::fs::File>> {
+impl TryFrom<std::path::PathBuf> for Decoder<BufReader<std::fs::File>> {
     type Error = DecoderError;
 
-    fn try_from(path: &std::path::Path) -> Result<Self, Self::Error> {
-        let file = std::fs::File::open(path).map_err(|e| Self::Error::IoError(e.to_string()))?;
-        Self::try_from(file)
-    }
-}
+    fn try_from(path: std::path::PathBuf) -> Result<Self, Self::Error> {
+        let ext = path.extension().and_then(|e| e.to_str());
+        let file = std::fs::File::open(&path).map_err(|e| DecoderError::IoError(e.to_string()))?;
 
-impl Decoder<BufReader<std::fs::File>> {
-    /// Creates a `Decoder` from any path-like type.
-    ///
-    /// This is a convenience method that accepts anything that can be converted to a `Path`,
-    /// including `&str`, `String`, `&Path`, `PathBuf`, etc. The file is opened and automatically
-    /// configured with optimal settings including file size detection and seeking support.
-    ///
-    /// # Errors
-    ///
-    /// Returns `DecoderError::UnrecognizedFormat` if the audio format could not be determined
-    /// or is not supported.
-    ///
-    /// Returns `DecoderError::IoError` if the file cannot be opened or its metadata cannot be read.
-    ///
-    /// # Examples
-    /// ```no_run
-    /// use rodio::Decoder;
-    /// use std::path::Path;
-    ///
-    /// // Works with &str
-    /// let decoder = Decoder::from_path("music.mp3").unwrap();
-    ///
-    /// // Works with String
-    /// let path = String::from("music.mp3");
-    /// let decoder = Decoder::from_path(path).unwrap();
-    ///
-    /// // Works with Path and PathBuf
-    /// let decoder = Decoder::from_path(Path::new("music.mp3")).unwrap();
-    /// ```
-    pub fn from_path(path: impl AsRef<std::path::Path>) -> Result<Self, DecoderError> {
-        let file = std::fs::File::open(path).map_err(|e| DecoderError::IoError(e.to_string()))?;
-        Self::try_from(file)
+        let len = file
+            .metadata()
+            .map_err(|e| DecoderError::IoError(e.to_string()))?
+            .len();
+
+        let mut builder = Self::builder()
+            .with_data(BufReader::new(file))
+            .with_byte_len(len)
+            .with_seekable(true);
+
+        if let Some(ext) = ext {
+            let hint = match ext {
+                "adif" | "adts" => "aac",
+                "caf" => "audio/x-caf",
+                "m4a" | "m4b" | "m4p" | "m4r" | "mp4" => "audio/mp4",
+                "bit" | "mpga" => "mp3",
+                "mka" | "mkv" => "audio/matroska",
+                "oga" | "ogm" | "ogv" | "ogx" | "spx" => "audio/ogg",
+                "wave" => "wav",
+                _ => ext,
+            };
+            builder = builder.with_hint(hint);
+        }
+
+        builder.build()
     }
 }