fix #9227 procs can now have multiple interleaved doc comments + runnableExamples and be docgen'd correctly (#14441)

* fix #9227 proc doc comments after 1st runnableExamples are not ignored anymore

compiler/docgen.nim

@@ -529,12 +529,38 @@ proc prepareExample(d: PDoc; n: PNode): string =
     for imp in imports: runnableExamples.add imp
     runnableExamples.add newTree(nkBlockStmt, newNode(nkEmpty), copyTree savedLastSon)
 
-proc getAllRunnableExamplesRec(d: PDoc; n, orig: PNode; dest: var Rope) =
+proc getAllRunnableExamplesRec(d: PDoc; n, orig: PNode; dest: var Rope, previousIsRunnable: var bool) =
-  if n.info.fileIndex != orig.info.fileIndex: return
+  ##[
+  previousIsRunnable: keep track of whether previous sibling was a runnableExample (true if 1st sibling though).
+  This is to ensure this works:
+  proc fn* =
+    runnableExamples: discard
+    ## d1
+    runnableExamples: discard
+    ## d2
+
+    ## d3 # <- this one should be out; it's part of rest of function body and would likey not make sense in doc comment
+
+  It also works with:
+  proc fn* =
+    ## d0
+    runnableExamples: discard
+    ## d1
+
+    etc
+  ]##
+  # xxx: checkme: owner check instead? this fails with the $nim/nimdoc/tester.nim test
+  # now that we're calling `genRecComment` only from here (to maintain correct order wrt runnableExample)
+  # if n.info.fileIndex != orig.info.fileIndex: return
   case n.kind
+  of nkCommentStmt:
+    if previousIsRunnable:
+      dest.add genRecComment(d, n)
+    previousIsRunnable = false
   of nkCallKinds:
     if isRunnableExamples(n[0]) and
         n.len >= 2 and n.lastSon.kind == nkStmtList:
+      previousIsRunnable = true
       let rdoccmd = prepareExample(d, n)
       var msg = "Example:"
       if rdoccmd.len > 0: msg.add " cmd: " & rdoccmd
@@ -555,12 +581,15 @@ proc getAllRunnableExamplesRec(d: PDoc; n, orig: PNode; dest: var Rope) =
         inc i
         nodeToHighlightedHtml(d, b, dest, {renderRunnableExamples}, nil)
       dest.add(d.config.getOrDefault"doc.listing_end" % id)
-  else: discard
+  else: previousIsRunnable = false
+
+  var previousIsRunnable2 = true
   for i in 0..<n.safeLen:
-    getAllRunnableExamplesRec(d, n[i], orig, dest)
+    getAllRunnableExamplesRec(d, n[i], orig, dest, previousIsRunnable2)
 
 proc getAllRunnableExamples(d: PDoc; n: PNode; dest: var Rope) =
-  getAllRunnableExamplesRec(d, n, n, dest)
+  var previousIsRunnable = true
+  getAllRunnableExamplesRec(d, n, n, dest, previousIsRunnable)
 
 proc isVisible(d: PDoc; n: PNode): bool =
   result = false
@@ -735,8 +764,13 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) =
   var result: Rope = nil
   var literal, plainName = ""
   var kind = tkEof
-  var comm = genRecComment(d, n)  # call this here for the side-effect!
+  var comm: Rope = nil
-  getAllRunnableExamples(d, n, comm)
+  # skipping this (and doing it inside getAllRunnableExamples) would fix order in
+  # case of a runnableExample appearing before a doccomment, but would cause other
+  # issues
+  comm.add genRecComment(d, n)
+  if n.kind in declarativeDefs:
+    getAllRunnableExamples(d, n, comm)
   var r: TSrcGen
   # Obtain the plain rendered string for hyperlink titles.
   initTokRender(r, n, {renderNoBody, renderNoComments, renderDocComments,