Added section about Guido's rejection comments.

This commit is contained in:
Marc-André Lemburg 2001-03-23 11:46:44 +00:00
parent 0a7cf61555
commit 4e71c5cd35
1 changed files with 71 additions and 1 deletions

View File

@ -168,7 +168,77 @@ Possible Problems
Besides generating a docstring for an otherwise undocumented
attribute there is no breakage.
Comments from our BDFL
Early comments on the PEP from Guido:
I "kinda" like the idea of having attribute docstrings (meaning
it's not of great importance to me) but there are two things I
don't like in your current proposal:
1. The syntax you propose is too ambiguous: as you say,
stand-alone string literal are used for other purposes and could
suddenly become attribute docstrings.
2. I don't like the access method either (__doc_<attrname>__).
The author's reply:
> 1. The syntax you propose is too ambiguous: as you say, stand-alone
> string literal are used for other purposes and could suddenly
> become attribute docstrings.
This can be fixed by introducing some extra checks in the
compiler to reset the "doc attribute" flag in the compiler
struct.
> 2. I don't like the access method either (__doc_<attrname>__).
Any other name will do. It will only have to match these
criteria:
* must start with two underscores (to match __doc__)
* must be extractable using some form of inspection (e.g. by using
a naming convention which includes some fixed name part)
* must be compatible with class inheritence (i.e. should be
stored as attribute)
Later on in March, Guido pronounced on this PEP in March 2001 (on
python-dev). Here are his reasons for rejection mentioned in
private mail to the author of this PEP:
...
It might be useful, but I really hate the proposed syntax.
a = 1
"foo bar"
b = 1
I really have no way to know whether "foo bar" is a docstring
for a or for b.
...
You can use this convention:
a = 1
__doc_a__ = "doc string for a"
This makes it available at runtime.
> Are you completely opposed to adding attribute documentation
> to Python or is it just the way the implementation works ? I
> find the syntax proposed in the PEP very intuitive and many
> other users on c.l.p and in private emails have supported it
> at the time I wrote the PEP.
It's not the implementation, it's the syntax. It doesn't
convey a clear enough coupling between the variable and the
doc string.
Copyright
This document has been placed in the Public Domain.