Re: [Pysdl-devel] Re: A little trivia

[Martijn F. <fa...@ve...>]

David Clark <David Clark wrote:
> 
> Thank you everyone for discussing these issues; I'm learning a lot. I
> see some people are referring to my pySDL documentation as they try to
> determine what's going on, so I'm going to say this as clearly as I can:
> 
> --->  I don't really know what I'm doing. <---

---> But at least you are doing something. <--- :)

> This has two obvious results:
> 
> 1) The documentation is incomplete. If you come up with any insight
> into the workings of SDL and pySDL, please let me know. If you feel
> that parts of the documentation are unclear or poorly worded, please
> tell me. You don't even have to supply replacement wording (as Martijn
> so kindly did)

Actually the original SDL documentation's wording was confusing (but it's fixed
in Sam Lantinga's header files now, so eventually that ought to show up
in the docs). So it wasn't your fault. :)

[snip]

> 2) The documentation is incorrect.

In this case, the SDL docs turned out to be incorrect; the SRCKEY and
SRCALPHA flags are *always* honored, no matter what the surface is,
apparently. Your docs were better, as I didn't find it saying they
weren't honored. ;)

> Don't rely on my understanding of
> the API for very much at this point. Read the SDL documentation too -
> in some cases (such as color shifts), I've just cut and pasted from
> there or from the __doc__ strings. Don't take what's written in the
> pySDL documentation as gospel until you've tested it in the real
> world.

And as my foray into the SDL docs showed, don't even take the SDL
documentation as gospel until you've tested it in the real world, or
at least until Mark has tested it in the real world and tells you. :)

Anyway, you're doing fine with the docs -- even when the docs are
excellent (SDL's docs are generally very nice) and written by the
original developer, obscure phrases and documentation inaccuracies
can sneak in, after all.

Thanks!

Martijn