>>>>> "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.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4