From acef01063c4d4aaaf1a22a212d245e82db2a37ee Mon Sep 17 00:00:00 2001 From: Timothee Cour Date: Sun, 24 May 2020 04:05:27 -0700 Subject: [PATCH 1/3] fix #9227 proc doc comments after 1st runnableExamples are not ignored anymore --- compiler/docgen.nim | 37 ++++++++++++++++++++++++++++++++----- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index a67dc48ec9c8..cbe7ef9ebb43 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -527,12 +527,36 @@ 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) = + ##[ + 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 + ]## 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 @@ -553,12 +577,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.. Date: Sun, 24 May 2020 05:02:25 -0700 Subject: [PATCH 2/3] test pass --- compiler/docgen.nim | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index cbe7ef9ebb43..96fb81d5bf43 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -547,7 +547,9 @@ proc getAllRunnableExamplesRec(d: PDoc; n, orig: PNode; dest: var Rope, previous etc ]## - if n.info.fileIndex != orig.info.fileIndex: return + # xxx: checkme: owner check instead? this fails with the $nim_prs_D/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: @@ -761,7 +763,15 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) = var literal, plainName = "" var kind = tkEof var comm: Rope = nil - getAllRunnableExamples(d, n, comm) + # if n.kind notin routineKinds: + # if n.kind notin declarativeDefs: + # comm.add genRecComment(d, n) + comm.add genRecComment(d, n) + dbg n.kind, n.renderTree, comm + # if n.kind notin declarativeDefs: + if n.kind in declarativeDefs: + getAllRunnableExamples(d, n, comm) + dbg comm var r: TSrcGen # Obtain the plain rendered string for hyperlink titles. initTokRender(r, n, {renderNoBody, renderNoComments, renderDocComments, From a2864563a3d5c398a3d1235d7a3f5d25a099c3c1 Mon Sep 17 00:00:00 2001 From: Timothee Cour Date: Sun, 24 May 2020 05:04:32 -0700 Subject: [PATCH 3/3] fixup --- compiler/docgen.nim | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 96fb81d5bf43..3dca4a23cb68 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -538,16 +538,16 @@ proc getAllRunnableExamplesRec(d: PDoc; n, orig: PNode; dest: var Rope, previous ## 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_prs_D/nimdoc/tester.nim test + # 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 @@ -763,15 +763,12 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) = var literal, plainName = "" var kind = tkEof var comm: Rope = nil - # if n.kind notin routineKinds: - # if n.kind notin declarativeDefs: - # comm.add genRecComment(d, n) + # 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) - dbg n.kind, n.renderTree, comm - # if n.kind notin declarativeDefs: if n.kind in declarativeDefs: getAllRunnableExamples(d, n, comm) - dbg comm var r: TSrcGen # Obtain the plain rendered string for hyperlink titles. initTokRender(r, n, {renderNoBody, renderNoComments, renderDocComments,