@Araq > Again, runnableExamples are not just documentation. They are also tests.
Does that mean there can be testing code in a block named runnable Example s which is run by the documentation generator, but not by the regular testing framework? Testing and doc examples are two different concerns IMHO. The point of compiling and/or running doc code examples should be to validate the examples, not to test the module. The correctness hierarchy should be tests -> code -> examples, not (tests and examples) -> code. @timothee > This isn't specific to Nim. The fact that it is linked to a block comment context while technically being code is specific, and that's the part that bothers me. > ... in D, unittest blocks are not embedded in documentation even though they > end up in documentation and can be run from html. TBH that sounds like a great solution: * devs looking at comments in the source are not confused by block comments mixed with code. * tests are clearly separated from documentation in the source and are honored by the doc generator and the compiler/testing framework (I assume). Can't we get something like this? If `runnableExamples` was renamed to something with `test` and detached from comments, the only missing part would be validation for actual doc example code, and that would be relatively straight-forward: the doc generator could just compile example code blocks in doc comments at the end of the module/scope. If `.. code-block:: nim` is too cumbersome to type, the doc generator could learn about fenced code blocks (```-blocks). > thanks for reporting this; but please report as github issue next time ... I didn't report it as an issue because I wasn't sure it is one or if it's just me not understanding the intended behavior of the code. > ... instead of forum to increase change it gets fixed ... That was not what I wanted, sorry if I made it look like that.
