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: Code: i = 0 while 1: try: fd = open('/tmp/junk%d' % i, 'r') # ith template file except IOError: return open('/tmp/junk%d' % i, 'w') # nonexistent file fd.close() 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 ... Eddy.