On Thu, Jul 30, 2009 at 7:55 PM, Greg Ewing
<greg.ewing@xxxxxxxxxxxxxxxx> wrote:
jug wrote:
http://pygameweb.no-ip.org/docs/surface.html ist not really easy to read, but I don't know exactly why.
It looks all right to me, except for one thing: Every
link to the docs for a method embedded in the text
seems to be followed by a comment in small print, e.g.
in the paragraph about Surface.convert,
...arguments can be used, similar to the
pygame.Surface - [pygame object for representing
images] call...
IMO these embedded comments are pointless and
distracting and make the text hard to read. Just
make the method name into a link and leave it at
that.
Also a minor suggestion would be to leave some
space between the heading for a method and its
call prototypes, and between the prototypes and the
following text, e.g. instead of
Surface.convert - change the pixel format of an image
Surface.convert(Surface): return Surface
Surface.convert(depth, flags=0): return Surface
Surface.convert(masks, flags=0): return Surface
Surface.convert(): return Surface
Creates a new copy of the Surface with the pixel format
changed. The new pixel format can...
space it out slightly:
Surface.convert - change the pixel format of an image
Surface.convert(Surface): return Surface
Surface.convert(depth, flags=0): return Surface
Surface.convert(masks, flags=0): return Surface
Surface.convert(): return Surface
Creates a new copy of the Surface with the pixel format
changed. The new pixel format can...
Also generally leave space between paragraphs if you're
not going to indent the first line of each paragraph.
Otherwise the text tends to look like one huge paragraph,
which is not good for reading.
--
Greg