close #12746; minor cleanup (#14379)

tests/nimdoc/readme.md

@@ -1,2 +1,3 @@
-the html validation is tested by nimdoc/tester.nim
-the runnableExamples + nim doc logic (across backend) is tested here
+## links
+* $nim/nimdoc/tester.nim: tests html validation
+* $nim/tests/nimdoc/: tests `runnableExamples` + `nim doc` logic

tests/nimdoc/trunnableexamples.nim

@@ -0,0 +1,79 @@
+discard """
+cmd: "nim doc $file"
+action: "compile"
+nimout: '''
+foo1
+foo2
+foo3
+foo5
+foo6
+foo7
+foo8
+foo9
+'''
+joinable: false
+"""
+
+proc fun*() =
+  runnableExamples:
+    block: # `defer` only allowed inside a block
+      defer: echo "foo1"
+
+  runnableExamples:
+    # `fun*` only allowed at top level
+    proc fun*()=echo "foo2"
+    fun()
+    block:
+      defer: echo "foo3"
+
+  runnableExamples:
+    # ditto
+    proc fun*()=echo "foo5"
+    fun()
+
+  runnableExamples:
+    # `codeReordering` only allowed at top level
+    {.experimental: "codeReordering".}
+    proc fun1() = fun2()
+    proc fun2() = echo "foo6"
+    fun1()
+
+  runnableExamples:
+    # only works at top level
+    import std/macros
+    macro myImport(a: static string): untyped =
+      newTree(nnkImportStmt, [newLit a])
+    myImport "str" & "utils"
+    doAssert declared(isAlphaAscii)
+    echo "foo7"
+
+when true: # issue #12746
+  # this proc on its own works fine with `nim doc`
+  proc goodProc*() =
+    runnableExamples:
+      try:
+        discard
+      except:
+        # just the general except will work
+        discard
+
+  # FIXED: this proc fails with `nim doc`
+  proc badProc*() =
+    runnableExamples:
+      try:
+        discard
+      except IOError:
+        # specifying Error is culprit
+        discard
+
+# also check for runnableExamples at module scope
+runnableExamples:
+  block:
+    defer: echo "foo8"
+
+runnableExamples:
+  proc fun*()=echo "foo9"
+  fun()
+
+# note: there are yet other examples where putting runnableExamples at module
+# scope is needed, for example when using an `include` before an `import`, etc.