@juancarlospaco > I think is an awesome feature, because other lang have DocTests or the like > (Python, Rust, etc), but the code is on comments, that means you dont have > any features of the IDE/Editor you are using, like syntax highlight, etc, is > still code on a comment.
True, but this is a shortcoming of the highlighter. Breaking separation of concerns by putting pure doc sample code _outside_ of doc comments which makes it look like regular code is the wrong answer. Searching for `runnableExamples` in Nim's github project even finds some code where it is used outside of any doc comment context, which means it is silently ignored. @arnetheduck Some very valid points. Also, `runnableExamples` just adds the caption **Examples:** above the code in the generated doc, which I really don't like. @dom96 Unfortunately, the `:test:` code block option is only supported by the `nim rst2html` sub-command, which takes rst input. `nim doc` doesn't understand it, so it cannot be used in source code comments. @timothee IMHO `nim doc` should support a `:compile:` option for the `code-block` directive which tries to compile the code block body on the source code level of the entity the comment is for. This should solve the sync problem.
