`runnableExample` is a bad idea and should die, here's why: 1\. It breaks separation of concerns. Code defines what a program does, comment gives information about that code. Two different concerns. Blurring the line by placing sample code for documentation purposes outside of a block comment and inside the actual code is therefore bad. It confuses people who are used to SOC and puts the compiler in a strange position: there's a standard lib proc which the compiler is supposed to ignore, but another entity (the doc generator) knows about. This makes `runnableExample` a unique case AFAIK, have fun explaining this to other tools / IDE code instrumentation.
2\. Comment has a higher semantic level than code, it is meta-information ABOUT code. Tools for a lower semantic level like the compiler should have to know as little as possible about higher semantic levels. Good old "ignore stuff that looks like a comment, everything else is for you" is a simple and proven rule for a compiler. We had "magical comments" that actually influence the compilation process in older languages, but this flaming nonsense with wings from hell has been abandoned in favor of annotations, Nim pragmas etc. for good reason. 3\. Nobody else does that. All other modern languages I know of keep sample code inside block comments. There may be other reasons for that than those given in this post.
