* let's not blow this out of proportion. Syntax highlighting could be made /
configured to colorize or italicize runnableExamples blocks so it's clear it's
part of documentation. Such tooling is much better than having to add
boilerplate like # #### Implementation ##### everywhere. A simple empty line
instead of # #### Implementation ##### is enough to separate proc doc comments
from proc implementation.
* once
[https://github.com/nim-lang/Nim/issues/9227](https://github.com/nim-lang/Nim/issues/9227)
is fixed, the drawbacks you mention are gone:
proc foo*()=
## proc doc comment part 1
runnableExamples: echo "ok1"
## proc doc comment part 2
runnableExamples: echo "ok2"
## proc doc comment part 3
## not part of proc doc comment
echo "ok3"
Run
* putting all runnableExamples at the end of the file is a bad idea as was
mentioned earlier: documentation should be right where the symbol is defined to
reduce having to jump around when reading/writing code (also it wouldn't allow
having code snippets with accompanying documentation)
* see also all the arguments I explained in
[https://forum.nim-lang.org/t/4274](https://forum.nim-lang.org/t/4274) which
aren't addressed by code-block
