Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 3 commits into from
May 25, 2020
Merged

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

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
acef010
fix #9227 proc doc comments after 1st runnableExamples are not ignore…
timotheecour May 24, 2020
2434841
test pass
timotheecour May 24, 2020
a286456
fixup
timotheecour May 24, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 41 additions & 7 deletions compiler/docgen.nim
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -527,12 +527,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
Expand All @@ -553,12 +579,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)
timotheecour marked this conversation as resolved.
Show resolved Hide resolved

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
Expand Down Expand Up @@ -733,8 +762,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,
Expand Down