docs: Update notes on SDL_AudioStream format management.

Fixes #15688.

include/SDL3/SDL_audio.h

@@ -434,7 +434,8 @@ typedef struct SDL_AudioSpec
  * - It can handle incoming data in any variable size.
  * - It can handle input/output format changes on the fly.
  * - It can remap audio channels between inputs and outputs.
- * - You push data as you have it, and pull it when you need it
+ * - You push data as you have it, and pull it when you need it; the
+ *   stream will buffer data as needed.
  * - It can also function as a basic audio data queue even if you just have
  *   sound that needs to pass from one place to another.
  * - You can hook callbacks up to them when more data is added or requested,
@@ -1054,8 +1055,15 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
 /**
  * Create a new audio stream.
  *
- * \param src_spec the format details of the input audio.
- * \param dst_spec the format details of the output audio.
+ * Note that `src_spec` or `dst_spec` may be NULL, but any attempts to
+ * put or get data from an audio stream will fail until it has valid
+ * specs assigned to both ends of the stream. Specs can be assigned later
+ * through SDL_SetAudioStreamFormat(), or binding the stream to an audio
+ * device (which will set the format of only the input or output,
+ * depending on what kind of device the stream was bound to).
+ *
+ * \param src_spec the format details of the input audio. May be NULL.
+ * \param dst_spec the format details of the output audio. May be NULL.
  * \returns a new audio stream on success or NULL on failure; call
  *          SDL_GetError() for more information.
  *
@@ -1137,6 +1145,9 @@ extern SDL_DECLSPEC bool SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *strea
  * be ignored, but this will not report an error. The other side's format can
  * be changed.
  *
+ * `src_spec` and `dst_spec` may each be NULL; a NULL spec signals not to
+ * change the current format for that side of the stream.
+ *
  * \param stream the stream the format is being changed.
  * \param src_spec the new format of the audio input; if NULL, it is not
  *                 changed.