mirrors/Nim
1
0
Fork 0
mirror of https://github.com/nim-lang/Nim.git synced 2026-01-03 19:52:36 +00:00
Code Issues Packages Projects Releases Wiki Activity

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

Browse Source 
* fix #9227 proc doc comments after 1st runnableExamples are not ignored anymore
This commit is contained in:
Timothee Cour
2020-05-25 06:44:23 -07:00
committed by GitHub
parent 6635874a85
commit f96555bd10
1 changed files with 41 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
compiler/docgen.nim
View File

@@ -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) =
if n.info.fileIndex != orig.info.fileIndex: return
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
]##
# 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!
getAllRunnableExamples(d, n, comm)
var comm: Rope = nil
# 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,