Sync wiki -> header

include/SDL_audio.h

@@ -521,7 +521,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index,
  * 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
+ * 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.
  *
@@ -994,10 +994,9 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst,
  * You should not call SDL_LockAudio() on the device before queueing; SDL
  * handles locking internally for this function.
  *
- * Note that SDL2
+ * Note that SDL2 does not support planar audio. You will need to resample
- * [https://discourse.libsdl.org/t/sdl2-support-for-planar-audio/31263/3 does
+ * from planar audio formats into a non-planar one (see SDL_AudioFormat)
- * not support planar audio]. You will need to resample from planar audio
+ * before queuing audio.
- * formats into a non-planar one (see SDL_AudioFormat) before queuing audio.
  *
  * \param dev the device ID to which we will queue audio
  * \param data the data to queue to the device for later playback

include/SDL_clipboard.h

@@ -53,12 +53,13 @@ extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
 /**
  * Get UTF-8 text from the clipboard, which must be freed with SDL_free().
  *
- * This functions returns NULL if there was not enough memory left for a copy
+ * This functions returns empty string if there was not enough memory left for
- * of the clipboard's content.
+ * a copy of the clipboard's content.
  *
- * \returns the clipboard text on success or NULL on failure; call
+ * \returns the clipboard text on success or an empty string on failure; call
  *          SDL_GetError() for more information. Caller must call SDL_free()
- *          on the returned pointer when done with it.
+ *          on the returned pointer when done with it (even if there was an
+ *          error).
  *
  * \sa SDL_HasClipboardText
  * \sa SDL_SetClipboardText

include/SDL_error.h

@@ -72,11 +72,11 @@ extern DECLSPEC int SDLCALL SDL_SetError(SDL_PRINTF_FORMAT_STRING const char *fm
  *
  * The message is only applicable when an SDL function has signaled an error.
  * You must check the return values of SDL function calls to determine when to
- * appropriately call SDL_GetError(). You should _not_ use the results of
+ * appropriately call SDL_GetError(). You should *not* use the results of
  * SDL_GetError() to decide if an error has occurred! Sometimes SDL will set
  * an error string even when reporting success.
  *
- * SDL will _not_ clear the error string for successful API calls. You _must_
+ * SDL will *not* clear the error string for successful API calls. You *must*
  * check return values for failure cases before you can assume the error
  * string applies.
  *

include/SDL_filesystem.h

@@ -55,7 +55,7 @@ extern "C" {
  *
  * - `resource`: bundle resource directory (the default). For example:
  *   `/Applications/SDLApp/MyApp.app/Contents/Resources`
- * - `bundle`: the Bundle directory. Fpr example:
+ * - `bundle`: the Bundle directory. For example:
  *   `/Applications/SDLApp/MyApp.app/`
  * - `parent`: the containing directory of the bundle. For example:
  *   `/Applications/SDLApp/`

include/SDL_surface.h

@@ -640,7 +640,7 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface
  *          call SDL_GetError() for more information.
  *
  * \sa SDL_AllocFormat
- * \sa SDL_ConvertSurfaceFormat
+ * \sa SDL_ConvertSurface
  * \sa SDL_CreateRGBSurface
  */
 extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat