[Doc-SIG] Cross-reference proposal
Edward Welbourne <firstname.lastname@example.org>
Wed, 9 Feb 2000 11:51:24 +0000
> 2. I *do* use comments in doc strings!
Not an issue. As I specified it, the use of #...# is for samples of
*code when they appear in text* within a doc string. Thus, for example:
One can call #open('/tmp/junk', 'w')# to obtain a scratch file or
one can use:
i = 0
try: fd = open('/tmp/junk%d' % i, 'r') # ith template file
return open('/tmp/junk%d' % i, 'w') # nonexistent file
i = 1 + i
The parser knows when it's in an embedded Code: block so regards # as
starting a comment in one of those; but where it meets # in the text of
a paragraph, it knows that it's the start of an in-text code fragment.
Furthermore, in a Code: block but after the first # on a line, we can
use #...# to delimit fragments of code appearing in a comment (just as
we can use *emphasis* in comments without the * being interpreted as
`multiply') and have the doc-string parser understand it as such.
If you're putting comments *against the text* in a doc string, # thus,
as opposed to *within an example block*, you're being gratuitously
perverse and you deserve everything you get ;^>
As to # not being pretty ... tough. Being unambiguous is important,
being easy to spot is important, being easy to type is important, being
pretty is what the down-stream tools support. Fontification and
colouring might be able to help, in the mean time ...