[I18n-sig] Re: Patch 101320: doc strings

[Barry A. Warsaw]

>>>>> "MvL" == Martin von Loewis <loewis@informatik.hu-berlin.de> writes:

    MvL> I don't see how this could work for doc strings of classes,
    MvL> methods and functions. Do you propose to write

    MvL> def foo():
    |   _("This does the foo thing.")
    |   pass

    MvL> That won't work; the parser won't recognize it as a doc
    MvL> string.

Martin's right.  Fortunately docstrings are rarely used by the program
itself (they are mostly used by outside tools, like help()/doc() or
IDE's or interactive interpreters).

One place a docstring /is/ used by the program and needs to be
translated is for script help messages.  In most of the executable
scripts I write, the file's docstring is the usage text, and I include
a function that prints the global __doc__.  If that first string in
the file is wrapped in _('') it won't be a docstring.  If it isn't
wrapped, it won't be translated.  Two solutions: either the extractor
needs to be smarter (and xpot currently is, but pygettext isn't), or
you can hack around it like so:

#! /usr/bin/env python
__doc__ = _("blech, my module doc string")

A second place I've used class docstrings inside a program is to
write the error messages for exception classes as the class's
docstring.  This can be done in other ways, but also either solution
above would work.

-Barry