Added section about Guido's rejection comments.
This commit is contained in:
parent
0a7cf61555
commit
4e71c5cd35
72
pep-0224.txt
72
pep-0224.txt
|
@ -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.
|
||||
|
|
Loading…
Reference in New Issue