Opaque documentation

Discussion in 'Python' started by egbert, Oct 28, 2005.

  1. egbert

    egbert Guest

    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
    ========================================================================
     
    egbert, Oct 28, 2005
    #1
    1. Advertisements

  2. egbert

    Ben Sizer Guest

    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
     
    Ben Sizer, Oct 28, 2005
    #2
    1. Advertisements

  3. egbert

    Mike Meyer Guest

    "Ben Sizer" <> 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 <> http://www.mired.org/home/mwm/
    Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information.
     
    Mike Meyer, Oct 28, 2005
    #3
  4. Mike Meyer <> wrote:

    > "Ben Sizer" <> 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
     
    Alex Martelli, Oct 29, 2005
    #4
    1. Advertisements

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Martin Meier

    opaque - Bedeutung ?

    Martin Meier, Sep 10, 2004, in forum: Java
    Replies:
    3
    Views:
    2,035
    Eric Sosman
    Sep 10, 2004
  2. Brian Tozer

    Semi-opaque colored background

    Brian Tozer, Feb 8, 2004, in forum: HTML
    Replies:
    11
    Views:
    5,006
    Steve Pugh
    Feb 9, 2004
  3. Beauregard T. Shagnasty

    IE hides inline images with opaque background

    Beauregard T. Shagnasty, Dec 31, 2004, in forum: HTML
    Replies:
    13
    Views:
    1,109
  4. Ellarco
    Replies:
    12
    Views:
    755
    Jerry Coffin
    Oct 3, 2003
  5. Capstar

    opaque style question

    Capstar, Apr 15, 2004, in forum: C Programming
    Replies:
    41
    Views:
    1,268
    Dan Pop
    Apr 20, 2004
  6. Labora

    Opaque data type

    Labora, Nov 17, 2004, in forum: C Programming
    Replies:
    1
    Views:
    434
    Michael Mair
    Nov 17, 2004
  7. chankl

    Opaque pointers

    chankl, Aug 17, 2006, in forum: C Programming
    Replies:
    18
    Views:
    870
    Dave Thompson
    Aug 28, 2006
  8. Richard Weeks

    implementing an opaque type

    Richard Weeks, Feb 26, 2007, in forum: C Programming
    Replies:
    3
    Views:
    450
    Chris Thomasson
    Feb 27, 2007
Loading...