[Doc-SIG] Cross-reference proposal

[Tony J Ibbs (Tibs)]

Looking at how one would delimit references to code items,
Edward Welbourne wrote, on 08 February 2000 16:00:
> I don't think $, @ and ! are good candidates, but they could work;
> however, how do folk feel about # as a marker ?  Since we're in a
> doc-string, it doesn't have any special meaning; nor do I think it
> sensible to include an end-of-line-comment in an inline-in-the-doc code
> fragment (as opposed to a code fragment displayed using a Code: block or
> >>>).  Thus #any.valid(python + ' code') is guaranteed(to, work)#.

I dislike "#" for two reasons:

1. I dislike it (i.e., it looks nasty to me). I find it visually distracting
to try to parse the Python comment character as something else, in a Python
file, and anyway, it just looks wrong (damn - that last isn't a very
convincing bit of the argument). Eddy and I have been known to disagree
about such things, of course.

2. I *do* use comments in doc strings! I do! As a strong believer in
comments, if I include code in a doc string, it's damn well likely to be
commented! - not least because it's probably copied from some actual code,
which probably has comments in it.

(sorry - this gets me in a ticklish spot, as it feels to me akin to the
tendency of people teaching programming languages to first say "comments are
good" and then present skads of examples where they don't use any, normally
with the excuse "but it's only short, and an example, so I haven't bothered.
Been there, seen that.)

Tibs	# no, I wouldn't say I overcomment my code...

--
Tony J Ibbs (Tibs)      http://www.tibsnjoan.demon.co.uk/
"How fleeting are all human passions compared with the massive
continuity of ducks." - Dorothy L. Sayers, "Gaudy Night"
My views! Mine! Mine! (Unless Laser-Scan ask nicely to borrow them.)