Sync SDL3 wiki -> header

[ci skip]

include/SDL3/SDL_begin_code.h

@@ -53,8 +53,8 @@
  *
  * SDL, on occasion, might deprecate a function for various reasons. However,
  * SDL never removes symbols before major versions, so deprecated interfaces
- * in SDL3 will remain available under SDL4, where it would be expected an
+ * in SDL3 will remain available under SDL4, where it would be expected an app
- * app would have to take steps to migrate anyhow.
+ * would have to take steps to migrate anyhow.
  *
  * On compilers without a deprecation mechanism, this is defined to nothing,
  * and using a deprecated function will not generate a warning.
@@ -66,9 +66,9 @@
 /**
  * A macro to tag a symbol as a public API.
  *
- * SDL uses this macro for all its public functions. On some targets, it
+ * SDL uses this macro for all its public functions. On some targets, it is
- * is used to signal to the compiler that this function needs to be exported
+ * used to signal to the compiler that this function needs to be exported from
- * from a shared library, but it might have other side effects.
+ * a shared library, but it might have other side effects.
  *
  * This symbol is used in SDL's headers, but apps and other libraries are
  * welcome to use it for their own interfaces as well.
@@ -81,13 +81,13 @@
  * A macro to set a function's calling conventions.
  *
  * SDL uses this macro for all its public functions, and any callbacks it
- * defines. This macro guarantees that calling conventions match between
+ * defines. This macro guarantees that calling conventions match between SDL
- * SDL and the app, even if the two were built with different compilers
+ * and the app, even if the two were built with different compilers or
- * or optimization settings.
+ * optimization settings.
  *
  * When writing a callback function, it is very important for it to be
- * correctly tagged with SDLCALL, as mismatched calling conventions can
+ * correctly tagged with SDLCALL, as mismatched calling conventions can cause
- * cause strange behaviors and can be difficult to diagnose. Plus, on many
+ * strange behaviors and can be difficult to diagnose. Plus, on many
  * platforms, SDLCALL is defined to nothing, so compilers won't be able to
  * warn that the tag is missing.
  *
@@ -112,8 +112,8 @@
 /**
  * A macro to demand a function be inlined.
  *
- * This is a command to the compiler to inline a function. SDL uses this
+ * This is a command to the compiler to inline a function. SDL uses this macro
- * macro in its public headers for a handful of simple functions. On compilers
+ * in its public headers for a handful of simple functions. On compilers
  * without forceinline support, this is defined to `static SDL_INLINE`, which
  * is often good enough.
  *
@@ -131,8 +131,8 @@
  * of a function like this is the C runtime's exit() function.
  *
  * This hint can lead to code optimizations, and help analyzers understand
- * code flow better. On compilers without noreturn support, this is
+ * code flow better. On compilers without noreturn support, this is defined to
- * defined to nothing.
+ * nothing.
  *
  * This symbol is used in SDL's headers, but apps and other libraries are
  * welcome to use it for their own interfaces as well.
@@ -147,10 +147,10 @@
  * This is almost identical to SDL_NORETURN, except functions marked with this
  * _can_ actually return. The difference is that this isn't used for code
  * generation, but rather static analyzers use this information to assume
- * truths about program state and available code paths. Specifically, this
+ * truths about program state and available code paths. Specifically, this tag
- * tag is useful for writing an assertion mechanism. Indeed, SDL_assert uses
+ * is useful for writing an assertion mechanism. Indeed, SDL_assert uses this
- * this tag behind the scenes. Generally, apps that don't understand the
+ * tag behind the scenes. Generally, apps that don't understand the specific
- * specific use-case for this tag should avoid using it directly.
+ * use-case for this tag should avoid using it directly.
  *
  * On compilers without analyzer_noreturn support, this is defined to nothing.
  *
@@ -192,23 +192,23 @@
 /**
  * A macro to tag a function's return value as critical.
  *
- * This is a hint to the compiler that a function's return value should not
+ * This is a hint to the compiler that a function's return value should not be
- * be ignored.
+ * ignored.
  *
  * If an NODISCARD function's return value is thrown away (the function is
  * called as if it returns `void`), the compiler will issue a warning.
  *
- * While it's generally good practice to check return values for errors,
+ * While it's generally good practice to check return values for errors, often
- * often times legitimate programs do not for good reasons. Be careful
+ * times legitimate programs do not for good reasons. Be careful about what
- * about what functions are tagged as NODISCARD. It operates best when
+ * functions are tagged as NODISCARD. It operates best when used on a function
- * used on a function that's failure is surprising and catastrophic; a good
+ * that's failure is surprising and catastrophic; a good example would be a
- * example would be a program that checks the return values of all its
+ * program that checks the return values of all its file write function calls
- * file write function calls but not the call to close the file, which it
+ * but not the call to close the file, which it assumes incorrectly never
- * assumes incorrectly never fails.
+ * fails.
  *
- * Function callers that want to throw away a NODISCARD return value can
+ * Function callers that want to throw away a NODISCARD return value can call
- * call the function with a `(void)` cast, which informs the compiler the
+ * the function with a `(void)` cast, which informs the compiler the act is
- * act is intentional.
+ * intentional.
  *
  * On compilers without nodiscard support, this is defined to nothing.
  *
@@ -220,8 +220,8 @@
  * A macro to tag a function as an allocator.
  *
  * This is a hint to the compiler that a function is an allocator, like
- * malloc(), with certain rules. A description of how GCC treats this
+ * malloc(), with certain rules. A description of how GCC treats this hint is
- * hint is here:
+ * here:
  *
  * https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html#index-malloc-function-attribute
  *
@@ -237,10 +237,9 @@
  * A macro to tag a function as returning a certain allocation.
  *
  * This is a hint to the compiler that a function allocates and returns a
- * specific amount of memory based on one of its arguments.
+ * specific amount of memory based on one of its arguments. For example, the C
- * For example, the C runtime's malloc() function could use this macro
+ * runtime's malloc() function could use this macro with an argument of 1
- * with an argument of 1 (first argument to malloc is the size of the
+ * (first argument to malloc is the size of the allocation).
- * allocation).
  *
  * On compilers without alloc_size support, this is defined to nothing.
  *