Improve documentation by specifying errors and behavior explicitly

[Wizzard033]

It'd be nice if functions could describe their behavior when errors occur. Instead, I'm just staring at the source code to decide whether to check certain functions for errors.

[grimfang4]

Can you give some examples to guide improvements?

[Wizzard033]

The following describes what happens in case an error occurs for GPU_Init

/*! Initializes SDL and SDL_gpu.  Creates a window and goes through the renderer order to create a renderer context.
 * \return Returns a valid GPU_Target* on success, and NULL on failure (pushes an error code when fails)
 * \see GPU_SetRendererOrder()
 */
DECLSPEC GPU_Target* SDLCALL GPU_Init(Uint16 w, Uint16 h, GPU_WindowFlagEnum SDL_flags);

This helps me to write failure-resistant code by relying on documented behavior

[grimfang4]

Looks like a good way to go. I think it'd be clearer if the error code description was in a separate Doxygen command, like either \remark or \post.