Ka-Ping Yee wrote, on 08 February 2000 21:45:
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... ?
My immediate (and thus emotional) response to that is "NO!". This seems to be for two reasons: 1. I don't want spurious extra references that I don't intend (this is important to me, but I can see from the above you might not care). 2. It's quite possible to use common words in ways which are *not* applicable for the cross-reference. Hmm - thinks a bit... OK, here we go with an example: def BLOCKS(text,delimiter): """Given text and a paragraph delimiter, return paragraph BLOCKS. burble burble burble on a flowline model burble. burble think of it as pieces of text flowing along a pipeline burble if something goes wrong such that the pipeline BLOCKS up burble burble. """ Not a *very* contrived example. I've "highlighted" the word "blocks" as best I can in email. Note that the second usage of the word in the doc string is *not* a candidate for cross referencing. Given the nature of the english language (I can't speak for others) such multiple binding of meaning for a single word is common. trying-to-give-constructive-criticism,honest-guv Tibs -- Tony J Ibbs (Tibs) http://www.tibsnjoan.demon.co.uk/ 'Tim happens. Get used to it'. (David Ascher, on the Doc-SIG) My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)