[Doc-SIG] Cross-reference proposal

[Ka-Ping Yee]

Tony J Ibbs wrote:
> that sure sounds to me like it could be a "simple bare word" - if I have a
> class called London that handles data relating to the city of London, then
> I'll certainly use the noun and the class name in the same text.

[...]

> The company I work for have a customer who are the Ordnance Survey for Great
> Britain (as opposed to the Ordnance Survey for Northern Ireland, who are
> *not* the same people). This is commonly abbreviated OS(GB) (strangely


Edward Welbourne wrote:
> 
> umm ... I believe the reverse.
>   * A string-processing function with an argument which decides whether
>     to capitalise the string is almost certain to use the verb
>     capitalise (in its Natural Language sense) in the course of its
>     account of the argument which it will, naturally, call `capitalise'.


So here are three examples of what Tony and Edward might consider
"unintended" references.

Let me ask a radical question: if you had a class named London in
your module, and you happened to mention the city of London in
your docstring somewhere -- what would be so wrong with linking
that mention to the class named London?

Or if you have an argument named "capitalise" and somewhere in the
documentation you use the word "capitalise" -- is it really a
problem that that word is interpreted as referring to the argument?

Surely if you "just happen" to use exactly the name of a class
in your module documentation somewhere, it's somehow related... ?


-- ?!ng