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.
--
Egbert Bouwman - Keizersgracht 197 II - 1016 DS Amsterdam - 020 6257991
================================================== ======================

[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

[Mike Meyer]

"Ben Sizer" <ky*****@gmail.com> writes:

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
--
Mike Meyer <mw*@mired.org> http://www.mired.org/home/mwm/
Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.

[Alex Martelli]

Mike Meyer <mw*@mired.org> wrote:

"Ben Sizer" <ky*****@gmail.com> writes:

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."

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