[Doc-SIG] Cross-reference proposal

Peter Funk pf@artcom-gmbh.de
Tue, 8 Feb 2000 14:12:02 +0100 (MET)


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.


> 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