Sync SDL2 wiki -> header

[ci skip]

include/SDL_surface.h

@@ -817,6 +817,45 @@ extern DECLSPEC int SDLCALL SDL_FillRects
  * The blit semantics for surfaces with and without blending and colorkey are
  * defined as follows:
  *
+ * RGBA to RGB:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ *   (using the source alpha-channel and per-surface alpha) SDL_SRCCOLORKEY
+ *   ignored.
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy RGB. * if
+ *   SDL_SRCCOLORKEY set, only copy the pixels matching the RGB values of the
+ *   source color key, ignoring alpha in the comparison.
+ *
+ * RGB to RGBA:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ *   (using the source per-surface alpha)
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy RGB, set
+ *   destination alpha to source per-surface alpha value.
+ * - both: * if SDL_SRCCOLORKEY set, only copy the pixels matching the source
+ *   color key.
+ *
+ * RGBA to RGBA:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ *   (using the source alpha-channel and per-surface alpha) * SDL_SRCCOLORKEY
+ *   ignored.
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy all of RGBA
+ *   to the destination. * if SDL_SRCCOLORKEY set, only copy the pixels
+ *   matching the RGB values of the source color key, ignoring alpha in the
+ *   comparison.
+ *
+ * RGB to RGB:
+ *
+ * - Source surface blend mode set to SDL_BLENDMODE_BLEND: * alpha-blend
+ *   (using the source per-surface alpha)
+ * - Source surface blend mode set to SDL_BLENDMODE_NONE: * copy RGB.
+ * - both: * if SDL_SRCCOLORKEY set, only copy the pixels matching the source
+ *   color key.
+ *
+ * You should call SDL_BlitSurface() unless you know exactly how SDL blitting
+ * works internally and how to use the other blit functions.
+ *
  * \returns 0 if the blit is successful, otherwise it returns -1.
  */
 #define SDL_BlitSurface SDL_UpperBlit