[Doc-SIG] Cross-reference proposal

[Greg Ward]

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