diff --git a/include/SDL_audio.h b/include/SDL_audio.h
index 0aa001764..bf4479d05 100644
--- a/include/SDL_audio.h
+++ b/include/SDL_audio.h
@@ -462,57 +462,6 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
  * hostname/IP address for a remote audio server, or a filename in the
  * diskaudio driver.
  *
- * When filling in the desired audio spec structure:
- *
- * - `desired->freq` should be the frequency in sample-frames-per-second (Hz).
- * - `desired->format` should be the audio format (`AUDIO_S16SYS`, etc).
- * - `desired->samples` is the desired size of the audio buffer, in _sample
- *   frames_ (with stereo output, two samples--left and right--would make a
- *   single sample frame). This number should be a power of two, and may be
- *   adjusted by the audio driver to a value more suitable for the hardware.
- *   Good values seem to range between 512 and 8096 inclusive, depending on
- *   the application and CPU speed. Smaller values reduce latency, but can
- *   lead to underflow if the application is doing heavy processing and cannot
- *   fill the audio buffer in time. Note that the number of sample frames is
- *   directly related to time by the following formula: `ms =
- *   (sampleframes*1000)/freq`
- * - `desired->size` is the size in _bytes_ of the audio buffer, and is
- *   calculated by SDL_OpenAudioDevice(). You don't initialize this.
- * - `desired->silence` is the value used to set the buffer to silence, and is
- *   calculated by SDL_OpenAudioDevice(). You don't initialize this.
- * - `desired->callback` should be set to a function that will be called when
- *   the audio device is ready for more data. It is passed a pointer to the
- *   audio buffer, and the length in bytes of the audio buffer. This function
- *   usually runs in a separate thread, and so you should protect data
- *   structures that it accesses by calling SDL_LockAudioDevice() and
- *   SDL_UnlockAudioDevice() in your code. Alternately, you may pass a NULL
- *   pointer here, and call SDL_QueueAudio() with some frequency, to queue
- *   more audio samples to be played (or for capture devices, call
- *   SDL_DequeueAudio() with some frequency, to obtain audio samples).
- * - `desired->userdata` is passed as the first parameter to your callback
- *   function. If you passed a NULL callback, this value is ignored.
- *
- * `allowed_changes` can have the following flags OR'd together:
- *
- * - `SDL_AUDIO_ALLOW_FREQUENCY_CHANGE`
- * - `SDL_AUDIO_ALLOW_FORMAT_CHANGE`
- * - `SDL_AUDIO_ALLOW_CHANNELS_CHANGE`
- * - `SDL_AUDIO_ALLOW_ANY_CHANGE`
- *
- * These flags specify how SDL should behave when a device cannot offer a
- * specific feature. If the application requests a feature that the hardware
- * doesn't offer, SDL will always try to get the closest equivalent.
- *
- * For example, if you ask for float32 audio format, but the sound card only
- * supports int16, SDL will set the hardware to int16. If you had set
- * SDL_AUDIO_ALLOW_FORMAT_CHANGE, SDL will change the format in the `obtained`
- * structure. If that flag was *not* set, SDL will prepare to convert your
- * callback's float32 audio to int16 before feeding it to the hardware and
- * will keep the originally requested format in the `obtained` structure.
- *
- * If your application can only handle one specific data format, pass a zero
- * for `allowed_changes` and let SDL transparently handle any differences.
- *
  * An opened audio device starts out paused, and should be enabled for playing
  * by calling SDL_PauseAudioDevice(devid, 0) when you are ready for your audio
  * callback function to be called. Since the audio driver may modify the