[pygame] Documenting the pygame C API and making the API consistent

[Lenard Lindstrom <len-l@xxxxxxxxx>]

Hi everyone,

A part of the preparation for pygame 2 I have documented the functions 
and types exported by various pygame extension modules. For instance, 
the pygame.surface module exports C functions for creating and accessing 
pygame.Surface instances. These are used in other modules, such as 
pygame.display and pygame.image, where surfaces are created. In total, 
twelve extension modules make C functions available for use in other 
extension modules.

While documenting the C API I renamed C types, functions, and variables 
to be consistent with Python's PEP 7. Names starting with 'Py' and 'Pg' 
were changed to use the 'pg' prefix. This avoids conflicts with possible 
future Python C functions as well as make the pygame naming convention 
consistent. I have also found other inconsistencies in the pygame C API. 
Functions that return a Python object are consistent in returning NULL 
to indicate an error. However, for functions that return an error code, 
some may use -1 to indicate an error, while others use 0. Should I make 
an effort to make pygame error handling consistent within the C API? 
Would it make sense to do this before pygame 1.9.4 is released, or wait 
until pygame 2? Python is not much help since it has mixed error codes 
within its C API.

Lenard Lindstrom