Docs: Added where missing corrected where wrong

Specifically the documentation for
 - UniformSourceIterator was incomplete it did not mention that it can
   change the sample type

Author: github-actions[bot]

src/decoder/mod.rs

@@ -23,6 +23,7 @@ mod mp3;
 #[cfg(feature = "symphonia")]
 mod read_seek_source;
 #[cfg(feature = "symphonia")]
+/// Symphonia decoders types
 pub mod symphonia;
 #[cfg(all(feature = "vorbis", not(feature = "symphonia-vorbis")))]
 mod vorbis;
@@ -36,11 +37,15 @@ pub struct Decoder<R>(DecoderImpl<R>)
 where
     R: Read + Seek;
 
+/// Source of audio samples from decoding a file that never ends. When the
+/// end of the file is reached the decoder starts again from the beginning.
+///
+/// Supports MP3, WAV, Vorbis and Flac.
 pub struct LoopedDecoder<R>(DecoderImpl<R>)
 where
     R: Read + Seek;
 
-// can not really reduce the size of the VorbisDecoder. There are not any
+// Cannot really reduce the size of the VorbisDecoder. There are not any
 // arrays just a lot of struct fields.
 #[allow(clippy::large_enum_variant)]
 enum DecoderImpl<R>
@@ -239,6 +244,10 @@ where
         #[cfg(not(feature = "symphonia"))]
         Err(DecoderError::UnrecognizedFormat)
     }
+
+    /// Builds a new looped decoder.
+    ///
+    /// Attempts to automatically detect the format of the source of data.
     pub fn new_looped(data: R) -> Result<LoopedDecoder<R>, DecoderError> {
         Self::new(data).map(LoopedDecoder::new)
     }
@@ -329,6 +338,7 @@ where
     }
 }
 
+#[allow(missing_docs)] // Reason: will be removed, see: #612
 #[derive(Debug)]
 pub enum Mp4Type {
     Mp4,

src/decoder/symphonia.rs

@@ -210,12 +210,16 @@ impl Source for SymphoniaDecoder {
 
 #[derive(Debug, thiserror::Error)]
 pub enum SeekError {
+    /// Could not get next packet while refining seek position
     #[error("Could not get next packet while refining seek position: {0:?}")]
     Refining(symphonia::core::errors::Error),
+    /// Format reader failed to seek
     #[error("Format reader failed to seek: {0:?}")]
     BaseSeek(symphonia::core::errors::Error),
+    /// Decoding failed retrying on the next packet failed
     #[error("Decoding failed retrying on the next packet failed: {0:?}")]
     Retrying(symphonia::core::errors::Error),
+    /// Decoding failed on multiple consecutive packets
     #[error("Decoding failed on multiple consecutive packets: {0:?}")]
     Decoding(symphonia::core::errors::Error),
 }

src/source/crossfade.rs

@@ -27,6 +27,11 @@ where
     input_fadeout.mix(input_fadein)
 }
 
+/// Mixes one sound fading out with another sound fading in for the given
+/// duration.
+///
+/// Only the crossfaded portion (beginning of fadeout, beginning of fadein) is
+/// covered.
 pub type Crossfade<I1, I2> = Mix<TakeDuration<I1>, FadeIn<TakeDuration<I2>>>;
 
 #[cfg(test)]

src/source/done.rs

@@ -6,7 +6,7 @@ use crate::{Sample, Source};
 
 use super::SeekError;
 
-/// When the inner source is empty this decrements an `AtomicUsize`.
+/// When the inner source is empty this decrements a `AtomicUsize`.
 #[derive(Debug, Clone)]
 pub struct Done<I> {
     input: I,
@@ -15,6 +15,8 @@ pub struct Done<I> {
 }
 
 impl<I> Done<I> {
+    /// When the inner source is empty the AtomicUsize passed in is decremented.
+    /// If it was zero it will overflow negatively.
     #[inline]
     pub fn new(input: I, signal: Arc<AtomicUsize>) -> Done<I> {
         Done {

src/source/empty.rs

@@ -17,6 +17,8 @@ impl<S> Default for Empty<S> {
 }
 
 impl<S> Empty<S> {
+    /// An empty source that immediately ends without ever returning a sample to
+    /// play
     #[inline]
     pub fn new() -> Empty<S> {
         Empty(PhantomData)

src/source/empty_callback.rs

@@ -13,9 +13,15 @@ pub struct EmptyCallback<S> {
 
 impl<S> EmptyCallback<S> {
     #[inline]
+    /// Create an empty source which executes a callback function.
+    /// Example use-case:
+    ///
+    /// Detect and do something when the source before this one has ended.
     pub fn new(callback: Box<dyn Send + Fn()>) -> EmptyCallback<S> {
         EmptyCallback {
+            #[allow(missing_docs)] // See: https://github.com/RustAudio/rodio/issues/615
             phantom_data: PhantomData,
+            #[allow(missing_docs)] // See: https://github.com/RustAudio/rodio/issues/615
             callback,
         }
     }

src/source/mod.rs

@@ -360,6 +360,9 @@ where
         stoppable::stoppable(self)
     }
 
+    /// Adds a method [`Skippable::skip`] for skipping this source. Skipping
+    /// makes Source::next() return None. Which in turn makes the Sink skip to
+    /// the next source.
     fn skippable(self) -> Skippable<Self>
     where
         Self: Sized,
@@ -374,7 +377,7 @@ where
     /// in the position returned by [`get_pos`](TrackPosition::get_pos).
     ///
     /// This can get confusing when using [`get_pos()`](TrackPosition::get_pos)
-    /// together with [`Source::try_seek()`] as the the latter does take all
+    /// together with [`Source::try_seek()`] as the latter does take all
     /// speedup's and delay's into account. Its recommended therefore to apply
     /// track_position after speedup's and delay's.
     fn track_position(self) -> TrackPosition<Self>
@@ -455,22 +458,32 @@ where
 
 // We might add decoders requiring new error types, without non_exhaustive
 // this would break users builds
+/// Occurs when try_seek fails because the underlying decoder has an error or
+/// does not support seeking.
 #[non_exhaustive]
 #[derive(Debug, thiserror::Error)]
 pub enum SeekError {
-    #[error("Streaming is not supported by source: {underlying_source}")]
+    /// On of the underlying sources does not support seeking
+    #[error("Seeking is not supported by source: {underlying_source}")]
     NotSupported { underlying_source: &'static str },
     #[cfg(feature = "symphonia")]
+    /// The symphonia decoder ran into an issue
     #[error("Error seeking: {0}")]
     SymphoniaDecoder(#[from] crate::decoder::symphonia::SeekError),
     #[cfg(feature = "wav")]
     #[error("Error seeking in wav source: {0}")]
+    /// The hound (wav) decoder ran into an issue
     HoundDecoder(std::io::Error),
+    // Prefer adding an enum variant to using this. Its meant for end users their
+    // own try_seek implementations
+    /// Any other error probably in a custom Source
     #[error("An error occurred")]
     Other(Box<dyn std::error::Error + Send>),
 }
 
 impl SeekError {
+    /// Will the source remain playing at its position before the seek or is it
+    /// broken?
     pub fn source_intact(&self) -> bool {
         match self {
             SeekError::NotSupported { .. } => true,

src/source/pausable.rs

@@ -4,7 +4,7 @@ use crate::{Sample, Source};
 
 use super::SeekError;
 
-/// Internal function that builds a `Pausable` object.
+/// Builds a `Pausable` object.
 pub fn pausable<I>(source: I, paused: bool) -> Pausable<I>
 where
     I: Source,
@@ -22,6 +22,12 @@ where
     }
 }
 
+/// Wraps a source and makes it pausable by calling [`Pausable::set_paused`] on
+/// this object. When the source is paused it returns zero value samples.
+///
+/// You can usually still use this from another source wrapping this one by
+/// calling `inner_mut` on it. Similarly this provides [`Pausable::inner`] and
+/// mutable/destructing variants for accessing the underlying source.
 #[derive(Clone, Debug)]
 pub struct Pausable<I> {
     input: I,

src/source/position.rs

@@ -17,6 +17,7 @@ pub fn track_position<I>(source: I) -> TrackPosition<I> {
     }
 }
 
+/// Tracks the elapsed duration since the start of the underlying source.
 #[derive(Debug)]
 pub struct TrackPosition<I> {
     input: I,

src/source/samples_converter.rs

@@ -6,18 +6,17 @@ use cpal::{FromSample, Sample as CpalSample};
 
 use super::SeekError;
 
-/// An iterator that reads from a `Source` and converts the samples to a specific rate and
-/// channels count.
-///
-/// It implements `Source` as well, but all the data is guaranteed to be in a single frame whose
-/// channels and samples rate have been passed to `new`.
+/// Wrap the input and lazily converts the samples it provides to the type
+/// specified by the generic parameter D
 #[derive(Clone)]
 pub struct SamplesConverter<I, D> {
     inner: I,
     dest: PhantomData<D>,
 }
 
 impl<I, D> SamplesConverter<I, D> {
+    /// Wrap the input and lazily converts the samples it provides to the type
+    /// specified by the generic parameter D
     #[inline]
     pub fn new(input: I) -> SamplesConverter<I, D> {
         SamplesConverter {