Opaque documentation

[Ben Sizer]

egbert wrote:
> Once in a while you come acros aline of documentation
> that you have to, or that invites you to, read it again.
> This is what I found in PyGTK:
>
>     The set_screen method sets the 'screen" property to
>     the gtk.gdk.Screen specified by screen. The "screen" property
>     contains the screen that the window is displayed on.

Clearly this is a violation of "once and only once". I'd reword it as:

    The set_screen method sets the property to the gtk.gdk specified
    by. The property contains the that the window is displayed on.

;)  Maybe if I was being less facetious, someone could reword it as:

    The set_screen method sets the 'screen" property to
    the supplied gtk.gdk.Screen object. This property
    contains the screen that the window is displayed on.

Documentation is often a problem with Python and its libraries, sadly.
The same almost certainly goes for most open source projects.

-- 
Ben Sizer