Hi! Ka-Ping Yee schrieb:
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.
Agreed. [...]
Note that simple bare words are never interpreted as references.
Why not? Of course this may go wrong, if you use very common words like 'a', 'is', 'so' ... as identifiers. But I don't believe, that this will happen too much. [...seven rules deleted...] your rules sound a little bit complicated. I think we should model the reference rules after the python namespace visibility rules, which apply to all identifiers in the python object to document, with the exceptional handling of 'self.' within the doc-strings of class-objects: When processing the doc-string of class 'Zot' simply imagine a virtual object instance of class 'Zot' named 'self'. This behaviour seems "obvious" to me. The outcome may not be so very different from what you described in your ruleset. Regards, Peter -- Peter Funk, Oldenburger Str.86, 27777 Ganderkesee, Tel: 04222 9502 70, Fax: -60