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

29 Mar 2002 10:56:22 +0900

>>>>> "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.