On 08 February 2000, Ka-Ping Yee said:
Note that simple bare words are never interpreted as references. To refer to something, an identifier must be capitalized and match a class name, or be followed with an open-parenthesis and match a function or method name, or be preceded by "self.".
Two things I'm uncomfortable with here: * implicit enforcement of case conventions (modules, attributes, and methods lower-case, classes in StudlyCaps). While I think case conventions are a good thing and I like to see them followed, I'm not sure that people who *don't* follow them should be effectively barred from writing "standard" docstrings. (But my bondage 'n discipline side is cheering, "Yeah! Go! Stick it to those non-conformist punks!") * I think I'd prefer to distinguish identifiers before the docstring processor should look at them. And I'm really not sure if raising the word "self" so high in the pantheon is a good idea; it *is* an excellent convention that everyone should follow (much more so than the case convention), but the *user* of a class doesn't refer to it as 'self' -- that's something you do only when you're inside the class. Eg. in a docstring I prefer to type and to read: Don't frob the 'foo' attribute; use 'set_foo()' instead. rather than Don't frob self.foo; use self.set_foo() instead. I think I agree with at least that much from StructuredText. Greg