Tarek Ziadé writes: > On Wed, Jul 1, 2009 at 1:44 PM, Paul Moore<p.f.mo...@gmail.com> wrote:
> > General rule - don't document (and commit yourself to) any > > internal details that the user can't access from the public > > API. It just makes backward compatibility harder to maintain. > > The purpose is to provide this documentation to third-party > projects that want to implement a packaging system on the top of > these classes. That's a judgment you must make. However, Paul's opinion seems to be that it is internal, and not needed by third-parties who are working "on the top" of these classes. If upon consideration you agree, you should take those "details" out of the PEP proper. If you disagree, you should promote them to the "official"/public API. The point of a PEP is not to construct a duck; it is to explain what "quack" means. > Maybe this should be removed from the PEP and but into another > document targeted to developers ? Yes. In the reference implementation (aka prototype), which should have its own documentation as usual. The reference implementation for the PEP shows *how* these things can be done. It must do that, or the PEP has no force. However, the reference implementation need not be "industrial strength"; the actual implementation that eventually goes into the stdlib may very well be an optimized and enhanced version with many data structures and algorithms that differ from the reference implementation. Another general principle: even in the draft PEP, say "is", not "will be". If you're wrong, and that won't work; if it's insufficiently precise; if you find a more elegant way to express the solution; if you simply haven't thought carefully about something yet; if, for whatever reason, you may need to change the PEP, then you change it in the next draft. That's why we have a review cycle, so you can change it. If you yourself have a question, or the draft is incomplete at some point, then you can explain in a note (either a footnote or parentheses). You can even mark a whole section as "speculative" (eg, "nothing in this section has been implemented yet, so everything is subject to change"). But a rule should be stated as a rule, and precisely, so that reviewers can criticize it accurately. If you're uncomfortable saying "is", then maybe that part of the draft isn't ready for public review yet. On the other hand, you can use the reviewers' knowledge here: write "A is B", then as a note "(In some cases A is actually C, and this should be treated specially. But how?)" _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
