[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [pygame] Using reStructuredText for document sources



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 <ncdave4life@xxxxxxxxx> wrote:
On Fri, Mar 4, 2011 at 12:49 AM, Lenard Lindstrom <len-l@xxxxxxxxx> 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 <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
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)