On Fri, Mar 4, 2011 at 1:06 AM, Lenard Lindstrom
<len-l@xxxxxxxxx> wrote:
One advantage with formal documentation is it can be kept synchronized with Python doc strings. The current Pygame doc system does this in a limited way. Hopefully a move to reST will encourage even greater coordination. How would this be done with a wiki? Only the author of a new Pygame feature knows what it should actually do.
Well, certainly the wiki documentation can contain links to, for example, pydoc output (or anything else).
Also, the author of a pygame feature can edit wiki pages as easily as can anyone else. If he's done a bang-up, comprehensive job of documenting his work in Python docstrings, then his wiki page edit might simply add something like, "For details on the API to wiggle the wozzle, see
the pydoc entry."
But if his documentation is incomplete, or contains errors, then the users who figure out what it actually does by playing with it can add their hard-won knowledge to the collective pool of information, by editing the wiki. And someone gets it wrong, then someone else will surely revert his edit or correct the error in some other way, in short order.
Unfortunately the existing docs containing many second hand guesses. How will a wiki give better descriptions. As a developer, it is as easy for me to edit the docs in SVN as a wiki page. The Python approach to cooperative documenting is to encourage users to submit patches which are then incorporated into the formal documents.
Good in theory. In practice, it doesn't happen. Pygame.org/docs/ is full of corrections submitted via the comment mechanism, some from over three years ago, which have still never been incorporated into the formal documents. For example:
Surface.blit
draw one image onto another
Surface.blit(source, dest, area=None, special_flags = 0): return Rect
May 16, 2007 8:51am - Anonymous
The first two arguments to Surface.blit() seem to be reversed.
To draw Surface "source" onto Surface "dest" the correct call is:
pygame.Surface.blit(dest, source, position)
or
dest.blit(source, position)
Example:
screen = pygame.display.set_mode((100,100))
screen.fill((255,255,255)) # white background
red_block = pygame.Surface((50,50))
red_block.fill((255,0,0))
# draw red block onto white background
screen.blit(red_block, (25,25))
pygame.display.update()
Note that this error remains uncorrected in the downloaded documentation to this day, at
I think it would be nearly impossible for someone to use pygame without the sort of information which is currently available only in the "comments."
But if the documentation had been in a wiki back in 2007, this wouldn't be a problem. This documentation error would have been fixed back then, probably by the anonymous pygame user who submitted this long ignored correction.