One useful thing we can accomplish, as others have pointed out, is to come up with clear and simple rules for referring to other objects in documentation. To start things off, let me try proposing a set of lookup rules for people to evaluate and shoot down. I list the rules to be applied in order of decreasing priority. When a rule applies but the referent object does not exist, we proceed to test any lower-priority rules that apply. 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.". 1. Text: "self." <identifier> "(" In: class or method docstring Example: "self.foo(" mentioned in class "Zot" a. Refers to: method Zot.foo() b. Refers to: method foo() inherited by Zot 2. Text: "self." <identifier> In: class or method docstring Example: "self.foo" mentioned in class "Zot" a. Refers to: attribute "foo" of Zot instances 3. Text: [ <identifier> "." ]+ <capitalized-identifier> In: any docstring Example: "pkg.bar.Zot" a. Refers to: class pkg.bar.Zot 4. Text: [ <identifier> "." ]+ <identifier> "(" In: any docstring Example: "pkg.bar.foo(" a. Refers to: function pkg.bar.foo() 5. Text: <capitalized-identifier not preceded by "."> In: any docstring Example: "Zot" mentioned in module "bar" a. Refers to: class bar.Zot 6. Text: <identifier not preceded by "."> "(" In: module or function docstring Example: "foo(" mentioned in module "bar" a. Refers to: function bar.foo() 7. Text: <identifier not preceded by "."> "(" In: class or method docstring Example: "foo(" mentioned in class "Zot" in module "bar" a. Refers to: method Zot.foo() b. Refers to: method foo() inherited by Zot c. Refers to: function bar.foo() I have attempted to make this set of rules complete while having the "obvious" behaviour. Is the suggested behaviour sufficiently obvious? I am aiming to eliminate the possibility that these rules ever fail in an unexpected way. #7 may be a bit much, but i would like to hear your opinions. I think i am comfortable with #7a,b,c. Have a look at each rule and see if you can imagine a case where it will do the wrong thing. I hope to be able to claim that each rule "just has to be right". Thanks for your time and input! -- ?!ng