From ca6bfb12244c5fd26865c6c361db725d27642f47 Mon Sep 17 00:00:00 2001
From: Jakub Stasiak <jakub@stasiak.at>
Date: Thu, 24 Oct 2019 23:07:02 +0200
Subject: [PATCH] Try to guide AudioDevice users towards the lock method

It took me a while to figure out how to update the callback data, maybe
this will help someone.
---
 src/sdl2/audio.rs | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/sdl2/audio.rs b/src/sdl2/audio.rs
index a0f6dedf..8d590b9d 100644
--- a/src/sdl2/audio.rs
+++ b/src/sdl2/audio.rs
@@ -70,6 +70,10 @@ use crate::sys::SDL_AudioStatus;
 
 impl AudioSubsystem {
     /// Opens a new audio device given the desired parameters and callback.
+    ///
+    /// If you want to modify the callback-owned data at a later point (for example to update
+    /// its data buffer) you're likely to be interested in the
+    /// [AudioDevice.lock method](audio/struct.AudioDevice.html#method.lock).
     #[inline]
     pub fn open_playback<'a, CB, F, D>(&self, device: D, spec: &AudioSpecDesired, get_callback: F) -> Result<AudioDevice <CB>, String>
     where CB: AudioCallback, F: FnOnce(AudioSpec) -> CB, D: Into<Option<&'a str>>,
@@ -79,6 +83,10 @@ impl AudioSubsystem {
 
     /// Opens a new audio device for capture (given the desired parameters and callback).
     /// Supported since SDL 2.0.5
+    ///
+    /// If you want to modify the callback-owned data at a later point (for example to update
+    /// its data buffer) you're likely to be interested in the
+    /// [AudioDevice.lock method](audio/struct.AudioDevice.html#method.lock).
     pub fn open_capture<'a, CB, F, D>(&self, device: D, spec: &AudioSpecDesired, get_callback: F) -> Result<AudioDevice <CB>, String>
         where CB: AudioCallback, F: FnOnce(AudioSpec) -> CB, D: Into<Option<&'a str>>,
     {
@@ -653,6 +661,9 @@ impl<CB: AudioCallback> AudioDevice<CB> {
     }
 
     /// Opens a new audio device for playback (given the desired parameters and callback).
+    ///
+    /// If you want to modify the callback-owned data at a later point (for example to update
+    /// its data buffer) you're likely to be interested in the [lock method](#method.lock).
     pub fn open_playback<'a, F, D>(a: &AudioSubsystem, device: D, spec: &AudioSpecDesired, get_callback: F) -> Result<AudioDevice <CB>, String>
         where
             F: FnOnce(AudioSpec) -> CB,
@@ -663,6 +674,9 @@ impl<CB: AudioCallback> AudioDevice<CB> {
 
     /// Opens a new audio device for capture (given the desired parameters and callback).
     /// Supported since SDL 2.0.5
+    ///
+    /// If you want to modify the callback-owned data at a later point (for example to update
+    /// its data buffer) you're likely to be interested in the [lock method](#method.lock).
     pub fn open_capture<'a, F, D>(a: &AudioSubsystem, device: D, spec: &AudioSpecDesired, get_callback: F) -> Result<AudioDevice <CB>, String>
         where
             F: FnOnce(AudioSpec) -> CB,