https://github.com/nim-lang/Nim/pull/9228 (nim doc can run code blocks) introduced this feature:
proc foo*() =
## Does something unexpected.
##
## .. code-block::
## :test:
## foo()
##
## Don't run it!
raise newException(Exception, "boo!")
Isn't that redundant with runnableExamples? When should one be preferred over the other?
If we're allowing runnable code embedded inside documentation, I've argued we might as well use the friendlier, shorter syntax runnableExamples:
proc foo*() =
## Does something unexpected.
##
## runnableExamples:
## foo()
##
## Don't run it!
raise newException(Exception, "boo!")
which also allows one-liners:
proc foo*() =
## Does something unexpected.
## runnableExamples: foo()
## Don't run it!
raise newException(Exception, "boo!")
Isn't that redundant with runnableExamples?
Exactly! That is my confusion too.
If there were a poll, I would vote to keep only runnableExamples.
Did you mean to put runnableExamples in comments? I have only seen them uncommented:
proc fill*[T](a: var openArray[T], first, last: Natural, value: T) =
## fills the slice ``a[first..last]`` with ``value``.
runnableExamples:
var a: array[6, int]
a.fill(1, 3, 9)
doAssert a == [0, 9, 9, 9, 0, 0]
fillImpl(a, first, last, value)
That gives this output: algorithm docs from devel docs