Opaque documentation

[egbert]

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.

The screen on the second line, before the period, is in italics,
if that helps.

I like these texts. Prose should not disclose its secrets at once.
If you have other examples, please let us know.

 

[Ben Sizer]

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.

 

[Mike Meyer]

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

You over-specified the last clause. It should say "most software
projects."

<mike

 

[Alex Martelli]

You over-specified the last clause. It should say "most software
projects."

You over-specified the last clause. It should say "most projects."


Alex