By using this site, you agree to our updated Privacy Policy and our Terms of Use. Manage your Cookies Settings.
439,985 Members | 1,575 Online
Bytes IT Community
+ Ask a Question
Need help? Post your question and get tips & solutions from a community of 439,985 IT Pros & Developers. It's quick & easy.

Opaque documentation

P: n/a
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
================================================== ======================
Oct 28 '05 #1
Share this Question
Share on Google+
3 Replies


P: n/a

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

Oct 28 '05 #2

P: n/a
"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.
Oct 28 '05 #3

P: n/a
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
Oct 29 '05 #4

This discussion thread is closed

Replies have been disabled for this discussion.