I guess what makes me reluctant to agree to the suggestions of having
more special characters with special syntactical meaning is that it
would only serve to complicate a language, one of whose most beautiful
aspects is its simplicity... I'm afraid it a) might become a slippery
slope for more of the same, and b) would make translation/portability
between different flavours of Smalltalk more difficult.

Just out of curiosity (not that I'd advocate this), would an
equivalent of the distinction between line comments and block
comments, e.g. in Java:

... some code ...
/* This is a block comment
   spanning multiple lines, including
   ... some more code ...
   // and even containing line comments
*/
... yet more code ...

give you what you're after?

Have you considered using other delimiters (such as curly brackets)
within comments to allow "double-click-and-do-it" execution?

Are you absolutely sure that class comments and protocols for "test
methods" won't do the job? In my experience, classes that are so
complex they need additional "documentation" should be broken down or,
if that's not at all possible, they should be thoroughly documented in
the class comment, with possible references in the methods (simply
"see class comment" should suffice). And class comments aren't parsed,
the code doesn't necessarily have to be valid, etc. Similarly,
consider breaking methods that absolutely need comments between lines
of code into smaller methods, so that you'll only need method comments
(even if those methods are only meant for testing/demonstration
purposes). But then, you probably knew people were going to suggest
that ;-)

Documentation for tutorials shouldn't necessarily all be in the code,
imho, there should be some accompanying medium like webpages or a PDF
or something (or a class comment?).

I realise this doesn't address all you were after, but maybe it'll at
least give you a few alternatives to consider =o)


On 1/2/08, Keith Hodges <keith_hodges at yahoo.co.uk> wrote:
> A slightly less radical solution which would offer the same benefit
> would be if the compiler stopped parsing if it encountered six or so
> comment quotes on a line like so. (perhaps this could be reduced to two)
>
> """"""
>
> I was asked what problem this is solving...
>
> 1. In particular I find it difficult to provide code snippets in method
> comments which work via select and do-it. particularly if these code
> snippets are themselves commented. I think that tutorial type
> documentation would benefit from this facility.
>
> 1b. Also I have a habit of putting test code in comments at the bottom
> of my methods, but again I can't comment or use quote characters in this
> code.
>
> 2. In some circumstances it is useful to use methods to hold data,
> however the restriction that that data be valid smalltalk code is a pain
> in some situations... i.e. the scripts in the dev image script manager
> are maintained and generated from methods. However they have to be
> manually pre-processed into valid smalltalk code escaping quotes and so
> forth.
>
> 3. This scheme allows packages to have their own script manager like
> documentation as classes within existing browser tools.
>
> Keith
>
>
>