diff options
| -rw-r--r-- | changelog.md | 3 | ||||
| -rw-r--r-- | compiler/docgen.nim | 22 | ||||
| -rw-r--r-- | compiler/docgen2.nim | 14 | ||||
| -rw-r--r-- | doc/docgen.rst | 1 |
4 files changed, 28 insertions, 12 deletions
diff --git a/changelog.md b/changelog.md index 086a242ec..1f2655d7a 100644 --- a/changelog.md +++ b/changelog.md @@ -35,6 +35,9 @@ ### Tool changes +- `jsondoc` now include a `moduleDescription` field with the module + description. `jsondoc0` shows comments as it's own objects as shown in the + documentation. ### Compiler changes diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 07f0e0378..de2a9831d 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -787,13 +787,13 @@ proc generateDoc*(d: PDoc, n, orig: PNode) = proc add(d: PDoc; j: JsonNode) = if j != nil: d.jArray.add j -proc generateJson*(d: PDoc, n: PNode) = +proc generateJson*(d: PDoc, n: PNode, includeComments: bool = true) = case n.kind of nkCommentStmt: - if startsWith(n.comment, "##"): - let stripped = n.comment.substr(2).strip - d.add %{ "comment": %stripped, "line": %n.info.line.int, - "col": %n.info.col } + if includeComments: + d.add %*{"comment": genComment(d, n)} + else: + add(d.modDesc, genComment(d, n)) of nkProcDef: when useEffectSystem: documentRaises(d.cache, n) d.add genJsonItem(d, n, n.sons[namePos], skProc) @@ -821,11 +821,11 @@ proc generateJson*(d: PDoc, n: PNode) = succ(skType, ord(n.kind)-ord(nkTypeSection))) of nkStmtList: for i in countup(0, sonsLen(n) - 1): - generateJson(d, n.sons[i]) + generateJson(d, n.sons[i], includeComments) of nkWhenStmt: # generate documentation for the first branch only: if not checkForFalse(n.sons[0].sons[0]): - generateJson(d, lastSon(n.sons[0])) + generateJson(d, lastSon(n.sons[0]), includeComments) else: discard proc genTagsItem(d: PDoc, n, nameNode: PNode, k: TSymKind): string = @@ -951,8 +951,12 @@ proc writeOutput*(d: PDoc, useWarning = false) = outfile.string) proc writeOutputJson*(d: PDoc, useWarning = false) = + var modDesc: string + for desc in d.modDesc: + modDesc &= desc let content = %*{"orig": d.filename, "nimble": getPackageName(d.conf, d.filename), + "moduleDescription": modDesc, "entries": d.jArray} if optStdout in d.conf.globalOptions: write(stdout, $content) @@ -962,7 +966,9 @@ proc writeOutputJson*(d: PDoc, useWarning = false) = write(f, $content) close(f) else: - discard "fixme: error report" + localError(d.conf, newLineInfo(d.conf, AbsoluteFile d.filename, -1, -1), + warnUser, "unable to open file \"" & d.destFile.string & + "\" for writing") proc commandDoc*(cache: IdentCache, conf: ConfigRef) = var ast = parseFile(conf.projectMainIdx, cache, conf) diff --git a/compiler/docgen2.nim b/compiler/docgen2.nim index 2171a7194..f2ac6c1a9 100644 --- a/compiler/docgen2.nim +++ b/compiler/docgen2.nim @@ -55,20 +55,26 @@ proc processNodeJson(c: PPassContext, n: PNode): PNode = result = n var g = PGen(c) if shouldProcess(g): - generateJson(g.doc, n) + generateJson(g.doc, n, false) -proc myOpen(graph: ModuleGraph; module: PSym): PPassContext = +template myOpenImpl(ext: untyped) {.dirty.} = var g: PGen new(g) g.module = module var d = newDocumentor(AbsoluteFile toFullPath(graph.config, FileIndex module.position), - graph.cache, graph.config) + graph.cache, graph.config, ext) d.hasToc = true g.doc = d result = g +proc myOpen(graph: ModuleGraph; module: PSym): PPassContext = + myOpenImpl(HtmlExt) + +proc myOpenJson(graph: ModuleGraph; module: PSym): PPassContext = + myOpenImpl(JsonExt) + const docgen2Pass* = makePass(open = myOpen, process = processNode, close = close) -const docgen2JsonPass* = makePass(open = myOpen, process = processNodeJson, +const docgen2JsonPass* = makePass(open = myOpenJson, process = processNodeJson, close = closeJson) proc finishDoc2Pass*(project: string) = diff --git a/doc/docgen.rst b/doc/docgen.rst index 65c7bd908..e6604d3bd 100644 --- a/doc/docgen.rst +++ b/doc/docgen.rst @@ -117,6 +117,7 @@ Output:: { "orig": "docgen_sample.nim", "nimble": "", + "moduleDescription": "This module is a sample", "entries": [ { "name": "helloWorld", |