From 689670d66c4a4004ca9abfbc19394b28600e6691 Mon Sep 17 00:00:00 2001
From: Petr Gladkikh <petrglad@gmail.com>
Date: Fri, 15 Nov 2024 19:57:36 +0400
Subject: [PATCH] UPdate documentation

Add an example for rodio::play()
Remove experimental API from rustdocs.
---
 src/lib.rs          | 20 ++++++++++++++++++++
 src/source/mod.rs   | 15 ++-------------
 src/spatial_sink.rs |  2 +-
 src/stream.rs       |  4 ++--
 4 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/src/lib.rs b/src/lib.rs
index 9c2428c..407785b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -38,6 +38,26 @@
 //! // so we need to keep the main thread alive while it's playing.
 //! std::thread::sleep(std::time::Duration::from_secs(5));
 //! ```
+//! You can use [rodio::play()] to do the above
+//! ```no_run
+//! use std::fs::File;
+//! use std::io::BufReader;
+//! use rodio::{Decoder, OutputStream, source::Source};
+//!
+//! // Get an output stream handle to the default physical sound device.
+//! // Note that no sound will be played if _stream is dropped
+//! let stream_handle = rodio::OutputStreamBuilder::try_default_stream()
+//!         .expect("open default audio stream");
+//!
+//! // Load a sound from a file, using a path relative to Cargo.toml
+//! let file = BufReader::new(File::open("examples/music.ogg").unwrap());
+//! rodio::play(&stream_handle.mixer(), file).unwrap();
+//!
+//! // The sound plays in a separate audio thread,
+//! // so we need to keep the main thread alive while it's playing.
+//! std::thread::sleep(std::time::Duration::from_secs(5));
+//! ```
+//!
 //!
 //! ## Sink
 //!
diff --git a/src/source/mod.rs b/src/source/mod.rs
index 4802e53..ceac73b 100644
--- a/src/source/mod.rs
+++ b/src/source/mod.rs
@@ -310,20 +310,9 @@ where
     ///
     /// let agc_source = source.automatic_gain_control(1.0, 4.0, 0.005, 5.0);
     ///
-    /// // Get a handle to control the AGC's enabled state (optional)
-    /// #[cfg(feature = "experimental")]
-    /// {
-    ///     let agc_control = agc_source.get_agc_control();
+    /// // Add the AGC-controlled source to the sink
+    /// sink.append(agc_source);
     ///
-    ///     // You can toggle AGC on/off at any time (optional)
-    ///     agc_control.store(false, std::sync::atomic::Ordering::Relaxed);
-    ///
-    ///     // Add the AGC-controlled source to the sink    
-    ///     sink.append(agc_source);
-    /// }
-    ///
-    /// // Note: Using agc_control is optional. If you don't need to toggle AGC,
-    /// // you can simply use the agc_source directly without getting agc_control.
     /// ```
     #[inline]
     fn automatic_gain_control(
diff --git a/src/spatial_sink.rs b/src/spatial_sink.rs
index bddd679..4d54c70 100644
--- a/src/spatial_sink.rs
+++ b/src/spatial_sink.rs
@@ -5,7 +5,7 @@ use std::time::Duration;
 use cpal::FromSample;
 
 use crate::dynamic_mixer::Mixer;
-use crate::source::Spatial;
+use crate::source::{SeekError, Spatial};
 use crate::{Sample, Sink, Source};
 
 /// A sink that allows changing the position of the source and the listeners
diff --git a/src/stream.rs b/src/stream.rs
index 9437930..6653899 100644
--- a/src/stream.rs
+++ b/src/stream.rs
@@ -183,12 +183,12 @@ fn clamp_supported_buffer_size(
 }
 
 /// Plays a sound once. Returns a `Sink` that can be used to control the sound.
-pub fn play<R>(stream: &Mixer<f32>, input: R) -> Result<Sink, PlayError>
+pub fn play<R>(mixer: &Mixer<f32>, input: R) -> Result<Sink, PlayError>
 where
     R: Read + Seek + Send + Sync + 'static,
 {
     let input = decoder::Decoder::new(input)?;
-    let sink = Sink::connect_new(stream);
+    let sink = Sink::connect_new(mixer);
     sink.append(input);
     Ok(sink)
 }