Re: [pygame] pygame documentation

["Mike C. Fletcher" <mcfletch@rogers.com>]

Jasper Phillips wrote:

> On Thu, 20 May 2004, Pete Shinners wrote:
>  
...

> Overall I find the pygame docs much more succinct, although the pyopengl
> docs are more comprehensive.  The main thing the pyopengl docs have that
> pygame docs don't are links to examples using the methods in question.  This
> is very nice, e.g.
>
> http://pyopengl.sourceforge.net/documentation/manual/glTexImage2D.3G.xml
>  
We have two major advantages with PyOpenGL; professionally written docs 
for the C level (and because of the low-level nature of C, those have to 
be fairly extensive), and a formal specification for the system.  We 
just take the C docs and drops in two sections, one with the Python 
signatures, and one with auto-generated links to Python sample code from 
various project's CVS repositories.

Verbosity at that level is a good thing IMO.  Most readers find the 
OpenGL reference docs quite terse, yet they explicitly cover each flag 
(with a paragraph describing the purpose and effect of each), each 
parameter, the major interactions between parameters, and generally a 
fairly good description of the why, and what for the function itself.

What's missing is the "how", which is what the links to Python sample 
code gives us.  The docs for a function are also cross-linked to related 
functions, which is a considerable help for those new to the system.  
The thing about the OpenGL reference is that you can almost imagine 
building your own OpenGL renderer from them... that spec-like text is 
going to be a little voluminous compared with user-only docs, but it 
does mean that everyone works from the same page so-to-speak.

I find the PyGame docs a little terse, but I can't say I've found them 
to be deficient (with sample code at hand, anyway).  They are a very 
different style, but that tends to make the system seem smaller, which 
is probably a good thing for not scaring new users :) .

Have fun,
Mike

________________________________________________
 Mike C. Fletcher
 Designer, VR Plumber, Coder
 http://members.rogers.com/mcfletch/
 blog: http://zope.vex.net/~mcfletch/plumbing/