[Doc-SIG] Cross-reference proposal

[Ka-Ping Yee]

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