> Syntax highlighting could be made.. That looks like introducing a problem, then coming up with lots of workarounds to deal with the fallout. The compiler becomes more complicated (because it must now deal with documentation special cases), and the documentation tool becomes more complicated (because it must now understand more "code" parts of the AST) - instead of simply extracting them and passing them cleanly between the layers. Once you're done with that, you have to teach all the other tools this distinction also, just to get back to the status quo where you were before.
> A simple empty line No, it's really not. Visually, there's nothing that says that this is not application code (apart from a really long name that you have to spend time parsing). It's customary to put an empty line after if's, when's and any other block-introducing syntax. It looks like application code (visually) and it behaves like application code (compiler has to process it and yet another addition in system.nim is needed - soon we'll start seeing more `when` jungles in the compiler proper to handle special cases as well, just like suggest and pretty). It prevents quick skimming to quickly determine where the boundary between comment and logic is - an extra comment section like @mratsim suggests makes it does make it clear - that's not very elegant though. > putting all runnableExamples at the end indeed - at the end, in a different file etc etc defeats the purpose of having in-line documentation to begin with - if it's that far out of sight, what's the purpose of including it at all? There are dozens of more elegant solutions to linking examples to code - including simply following imports and conventions (just like unit tests). > one-liners I think in this case, what's being addressed is quality documentation - not sure a one-liner does that much to help explain an API that is sufficiently complex to warrant an example to begin with. Not that it should be hard to add examples - and indeed, in markdown, it's a breeze, and _[everyone](https://forum.nim-lang.org/postActivity.xml#everyone) knows how to do it, by now - triple-quotes, and you're typing code. If there's any special commenting-code feature that editors are likely to have out-of-the box, it's treating markdown code blocks as code. > practice no one uses it Perhaps that's a signal? not put them in documentation to start with, and have them in external files that get pulled in by convention, without runnableExamples? Go addresses it this way ([https://blog.golang.org/examples](https://blog.golang.org/examples)) - the good thing about it is that you then have control over the context in which the example is being run - imports, nesting, already existing variables etc instead of relying on the magic of the doc tool. Then the example can be documented as a document-block on the example function itself.
