*Oops!* I was obviously too hastly picking my example. As Mr. Anonymous wrote in his next comment, back in 2007:
*May 16, 2007 9:15am - Anonymous* Actually, on re-reading the method description, I realize that the "dest" argument means the position to where the source Surface should be copied too. So the call synopsis is equivalent to the second case in my comment. The naming of the arguments is a bit confusing, IMHO, and also that it is not (visually) clear that the documentation describes the methods of a Surface object instance and makes no mention of the class methods. Still, the comments are invaluable. Dave On Fri, Mar 4, 2011 at 2:04 AM, David Burton <ncdave4l...@gmail.com> wrote: > On Fri, Mar 4, 2011 at 12:49 AM, Lenard Lindstrom <le...@telus.net> wrote: > > > >> ... As for comments, they can be hidden. But some way is needed to flush >> them. Maybe comments should only be allowed for the frequently updated docs, >> with comments older than (let's say) six months automatically deleted. >> >> > > > *NOOOOOO!!!* > > The first thing I do whenever I go to a doc page is click on "show all > comments." (That *should* be the default!) > > Obviously *some* of the comments are junk spam, but many of the comments > are absolutely essential documentation for pygame, which should *never* be > deleted, except as they are merged into the non-comment documentation. > > > > On Fri, Mar 4, 2011 at 1:06 AM, Lenard Lindstrom <le...@telus.net> 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 <http://someplace.else.on.pygame.org/>." > > 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 > file:///c:\Python31\Lib\site-packages\pygame\docs\index.html > > 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. > > Dave > > -- “If anyone thinks the words ‘government’ and ‘efficiency’ belong in the same sentence, we have counseling available.” - Sen. Paul Tsongas (D-MA)
