[Python-Dev] Which doc is authoritative? [was: Deprecating string exceptions]

[Stephen J. Turnbull]

>>>>> "Skip" == Skip Montanaro <skip@pobox.com> writes:

    Skip> I'd then advocate that the module doc string simply refer to
    Skip> the libref docs for the hierarchy.

Except that as I understand it, the libref docs are separate from the
sources, and written in a different language.  I know that Emacs and
XEmacs manuals are continuously different from the docstrings, and the
docstrings are usually more accurate for two reasons:

(1) The docstrings are written by people who have just implemented the
    behavior described, in a form which does not require shifting
    mental gears.  {C,Lisp} -> Texinfo is hard to get right.  Requires
    validating-by-doc-build, so, ok, I can do that later<wink>.

(2) Docstrings are a perfect forum for the "many eyes" to make small
    contributions, and we get a lot of them.  It is counterproductive
    to say "this is no good without a corresponding Texinfo patch."

NB.  Unlike Emacs Lisp, whose definition is "emergent" from the
development process, Python (as I understand it) has a more formal
definition process, even for the libraries.  So Skip has a good solid
theoretical basis for his position IMHO.

just-trying-to-confuse-you-with-facts-ly y'rs


-- 
Institute of Policy and Planning Sciences     http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba                    Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
              Don't ask how you can "do" free software business;
              ask what your business can "do for" free software.