As a counterpoint to [https://forum.nim-lang.org/t/4274](https://forum.nim-lang.org/t/4274):
Just learned about runnableExamples from some pull requests and forum topics - and would like to share several concerns before this proliferates too widely (rationale repeated from above post, for convenience): 1\. By putting an example code block together with the actual logic of the function, it's hard to tell what is real code and what doesn't get executed - it all looks the same. Tricks like adding extra indent don't really help, it still looks/parses like logic in editors that do syntax highlighting - no clear boundary, thus extra effort is required to understand where documentation ends. It's also hard to teach - it adds another exception to the normal expectation that code that's written will actually get executed. 2\. In good documentation, examples are often interspersed with explanations - again, doing this with runnableExamples is hard - you have to add a comment block, end it, and start a new one after the example - reading the documentation becomes a very uneven process. Also, control over placement of the examples is lost. 3\. The big difference between RST and Markdown is that the former is structured - it's easy/well-specified how to extract blocks from it. If this feature is not used, there is absolutely no reason at all to go with this otherwise dead format - Markdown won the war, and having to switch to RST just for Nim for no gain is a PITA - akin to someone giving you a CD and expecting you to be able to listen to it. One language that does this really well is Rust, see for example this piece for Result: [https://doc.rust-lang.org/std/result/index.html](https://doc.rust-lang.org/std/result/index.html) [https://doc.rust-lang.org/src/core/result.rs.html#11](https://doc.rust-lang.org/src/core/result.rs.html#11) Several points can be seen there: * docs and examples are interspersed, and the author controls what goes where * docs are compiled and executed during build, as if they were unit tests / doctests - there are no technical reasons why this cannot be done All in all, I believe leaving this feature in will be a hindrance for having good documentation in nim, for several reasons: * Existing documentation would have to be updated to become consistent - this requires manpower - if this doesn't happen, documentation authors that want to contribute will spend time on deciding between the two formats instead of actually writing documentation * The limitations above means only trivial / minimal documentation can be supported due to lack of flexibility - it puts an upper bound on the quality that an author can achieve
