[niemeyer@conectiva.com: Re: [Python-Dev] Python's footprint]

[Skip Montanaro]

    >> I would much prefer the documentation make it eas(y|ier) to identify
    >> platform differences.  This holds true for docstrings, because they
    >> are the most readily available documentation format.

    Guido> But what about optional features that are only available on
    Guido> platform X?  Do you really want those to clutter up the docstring
    Guido> on platforms where they aren't available?  On the platform where
    Guido> they *are*, their docstring should have a "(Platform X only)"
    Guido> note.

Perhaps I should take a half-step back under Guido's withering stare.
That's probably why I've been feeling a chill all day... ;-)

I don't think it's necessary for the docstring to contain all the
excruciating detail available in the library reference manual, but I think a
quick

    help(open)

at the interpreter prompt or a docstring popped up in PyCrust or other
IDE-like thing should give you an indication that there are semantic
differences for that function across platforms.  Ideally, these differences
would only be documented at the highest level they can come into play.  For
example, if a class or module exhibits some platform-dependency, its
docstring would indicate that, not the docstring of every one of its
methods.  Also, consider time.strptime.  It's not always available, so the
time module's docstring should mention its possible absence depending on
platform.  On platforms where it's not supported, putting a "platform x
only" note in strptime's docstring won't help much to the confused
programmer wondering where to disappeared to.

Of course, it's easy for me to spout platitudes here.  Adjusting to such a
convention will probably add a fair amount of work to somebody's already
full schedule.

Skip