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

[Skip Montanaro]

    >> If there is platform-specific functionality, the docstring should
    >> document that only on the platform where it applies.

    mal> Just to make sure... I was talking about something like:

    mal> open__doc__ = \
    mal>     "Open the file. On Windows, the MBCS encoding is assumed, "\
    mal>     "on all other systems, the file name must be given in ASCII.";

+1

    mal> vs.

    mal> #ifdef MS_WINDOWS
    mal> open__doc__ = \
    mal>     "Open the file, assuming the filename is given in the MBCS "\
    mal>     "encoding.";
    mal> #else
    mal> open__doc__ = \
    mal>     "Open the file, assuming the filename is given in ASCII.";
    mal> #endif

-1

I agree w/ MAL.  I happen to be developing an application on Linux right
now, but I'm interested in where I might encounter problems when it migrates
to Windows.  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.

Skip