From ec76b0b9d3d156edb78dc278b77313f1af89cfc2 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Fri, 1 Sep 2023 09:01:03 +1000 Subject: [PATCH 01/12] Add --raw switch Chose that name since thats what the issue had, open to suggestions for any other name --- compiler/commands.nim | 3 +++ compiler/options.nim | 4 ++++ 2 files changed, 7 insertions(+) diff --git a/compiler/commands.nim b/compiler/commands.nim index 879a995882b6e..6f1e8af4fa4d6 100644 --- a/compiler/commands.nim +++ b/compiler/commands.nim @@ -1076,6 +1076,9 @@ proc processSwitch*(switch, arg: string, pass: TCmdLinePass, info: TLineInfo; of "shownonexports": expectNoArg(conf, switch, arg, pass, info) showNonExportedFields(conf) + of "raw": + expectNoArg(conf, switch, arg, pass, info) + docRawOutput(conf) of "exceptions": case arg.normalize of "cpp": conf.exc = excCpp diff --git a/compiler/options.nim b/compiler/options.nim index 0ef65a14048e9..064e3f59d06bf 100644 --- a/compiler/options.nim +++ b/compiler/options.nim @@ -110,6 +110,7 @@ type # please make sure we have under 32 options optEnableDeepCopy # ORC specific: enable 'deepcopy' for all types. optShowNonExportedFields # for documentation: show fields that are not exported optJsBigInt64 # use bigints for 64-bit integers in JS + optDocRaw # for documentation: Don't render HTML for JSON output TGlobalOptions* = set[TGlobalOption] @@ -1036,6 +1037,9 @@ proc isDynlibOverride*(conf: ConfigRef; lib: string): bool = proc showNonExportedFields*(conf: ConfigRef) = incl(conf.globalOptions, optShowNonExportedFields) +proc docRawOutput*(conf: ConfigRef) = + incl(conf.globalOptions, optDocRaw) + proc expandDone*(conf: ConfigRef): bool = result = conf.ideCmd == ideExpand and conf.expandLevels == 0 and conf.expandProgress From 4d04374d8ed93af7b8aeb3efc38710d6c3415471 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Fri, 1 Sep 2023 09:12:58 +1000 Subject: [PATCH 02/12] Add test case --- tests/misc/mrawjson.nim | 4 ++++ tests/misc/trunner.nim | 13 +++++++++++++ 2 files changed, 17 insertions(+) create mode 100644 tests/misc/mrawjson.nim diff --git a/tests/misc/mrawjson.nim b/tests/misc/mrawjson.nim new file mode 100644 index 0000000000000..d99e57113b9ff --- /dev/null +++ b/tests/misc/mrawjson.nim @@ -0,0 +1,4 @@ +## Module description. See [someProc] + +proc someProc*(a, b: int) = + ## Code should be used like `someProc(1, 2)` diff --git a/tests/misc/trunner.nim b/tests/misc/trunner.nim index 6e5487d1b76a0..bfc54c71ad390 100644 --- a/tests/misc/trunner.nim +++ b/tests/misc/trunner.nim @@ -251,6 +251,19 @@ sub/mmain.idx""", context doAssert doSomething["col"].getInt == 0 doAssert doSomething["code"].getStr == "proc doSomething(x, y: int): int {.raises: [], tags: [], forbids: [].}" + block: # nim jsondoc --raw switch + let file = testsDir / "misc/mrawjson.nim" + let destdir = testsDir / "misc/rawjsondocs" + removeDir(destDir) + defer: removeDir(destDir) + let (msg, exitCode) = execCmdEx(fmt"{nim} jsondoc --raw {file}") + doAssert exitCode == 0, msg + + let data = parseJson(readFile(destDir / "mrawjson.json")) + doAssert data["moduleDescription"].getStr == "Module description. See [someProc]" + let someProc = data["entries"][0] + doAssert someProc["description"].getStr == "Code should be used like `someProc(1, 2)`" + block: # further issues with `--backend` let file = testsDir / "misc/mbackend.nim" var cmd = fmt"{nim} doc -b:cpp --hints:off --nimcache:{nimcache} {file}" From 924482053e067299d7594c4e8495d307b94d6950 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Sat, 2 Dec 2023 11:41:18 +1100 Subject: [PATCH 03/12] Start removing the renderer when raw switch is enabled --- compiler/docgen.nim | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 2b25ded7df2ce..f95c47cd4fa60 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -21,6 +21,7 @@ import trees, types, typesrenderer, astalgo, lineinfos, pathutils, nimpaths, renderverbatim, packages +from sigmatch {.all.} import extractDocComment import packages/docutils/rstast except FileIndex, TLineInfo import std/[os, strutils, strtabs, algorithm, json, osproc, tables, intsets, xmltree, sequtils] @@ -1164,6 +1165,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): JsonItem = if not isVisible(d, nameNode): return var + plainDocs = n.getPlainDocstring() name = getNameEsc(d, nameNode) comm = genRecComment(d, n) r: TSrcGen @@ -1176,9 +1178,12 @@ proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): "col": %n.info.col} ) if comm != nil: - result.rst = comm - result.rstField = "description" - if r.buf.len > 0: + if optDocRaw in d.conf.options: + result.json["description"] = plainDocs + else: + result.rst = comm + result.rstField = "description" + elif r.buf.len > 0: result.json["code"] = %r.buf if k in routineKinds: result.json["signature"] = newJObject() From c3f0385db6f5b7fe1f0c0e793344e634b04f088d Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Wed, 3 Jan 2024 22:44:37 +1100 Subject: [PATCH 04/12] Basic system thats working Now we remove the rst field so that it doesn't try and render it and instead set the description ourselves --- compiler/docgen.nim | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index f95c47cd4fa60..a676cd497568b 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -21,7 +21,6 @@ import trees, types, typesrenderer, astalgo, lineinfos, pathutils, nimpaths, renderverbatim, packages -from sigmatch {.all.} import extractDocComment import packages/docutils/rstast except FileIndex, TLineInfo import std/[os, strutils, strtabs, algorithm, json, osproc, tables, intsets, xmltree, sequtils] @@ -468,6 +467,14 @@ proc genRecComment(d: PDoc, n: PNode): PRstNode = else: result = genRecCommentAux(d, n) +proc findDocString(n: PNode): string = + result = "" + if n.comment != "": + result = n.comment + elif n.kind in {nkProcDef, nkFuncDef, nkMethodDef, nkIteratorDef, + nkMacroDef, nkTemplateDef, nkConverterDef}: + result = findDocString(n[bodyPos]) + proc getPlainDocstring(n: PNode): string = ## Gets the plain text docstring of a node non destructively. ## @@ -1165,7 +1172,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): JsonItem = if not isVisible(d, nameNode): return var - plainDocs = n.getPlainDocstring() + plainDocs = n.findDocString() name = getNameEsc(d, nameNode) comm = genRecComment(d, n) r: TSrcGen @@ -1178,8 +1185,8 @@ proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): "col": %n.info.col} ) if comm != nil: - if optDocRaw in d.conf.options: - result.json["description"] = plainDocs + if optDocRaw in d.conf.globalOptions: + result.json["description"] = %plainDocs else: result.rst = comm result.rstField = "description" From d0b35709fa0e1e8f22b632835533653c693ce9a0 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Wed, 25 Dec 2024 20:55:40 +1100 Subject: [PATCH 05/12] Move the process for the raw check further into `genComment`. Means less edge cases from needing to handle it at the edges Uses optionals to represent the nil state --- compiler/docgen.nim | 70 ++++++++++++++++++++++++++---------------- tests/misc/trunner.nim | 11 +++---- 2 files changed, 49 insertions(+), 32 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index a676cd497568b..4a716e671d483 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -24,6 +24,7 @@ import import packages/docutils/rstast except FileIndex, TLineInfo import std/[os, strutils, strtabs, algorithm, json, osproc, tables, intsets, xmltree, sequtils] +import std/options as optionals from std/uri import encodeUrl from nodejs import findNodeJs @@ -431,36 +432,45 @@ proc getVarIdx(varnames: openArray[string], id: string): int = return i result = -1 -proc genComment(d: PDoc, n: PNode): PRstNode = +func initItemFragment(rst: PRstNode): ItemFragment = + ItemFragment(isRst: true, rst: rst) + +func initItemFragment(str: string): ItemFragment = + ItemFragment(isRst: false, str: str) + +proc genComment(d: PDoc, n: PNode): Option[ItemFragment] = if n.comment.len > 0: + if optDocRaw in d.conf.globalOptions: + return some initItemFragment(n.comment) + d.sharedState.currFileIdx = addRstFileIndex(d, n.info) try: - result = parseRst(n.comment, + result = some initItemFragment(parseRst(n.comment, toLinenumber(n.info), toColumn(n.info) + DocColOffset, - d.conf, d.sharedState) + d.conf, d.sharedState)) except ERecoverableError: - result = newRstNode(rnLiteralBlock, @[newRstLeaf(n.comment)]) + result = some initItemFragment(newRstNode(rnLiteralBlock, @[newRstLeaf(n.comment)])) else: - result = nil + result = none(ItemFragment) -proc genRecCommentAux(d: PDoc, n: PNode): PRstNode = - if n == nil: return nil +proc genRecCommentAux(d: PDoc, n: PNode): Option[ItemFragment] = + if n == nil: return none(ItemFragment) result = genComment(d, n) - if result == nil: + if result.isNone: if n.kind in {nkStmtList, nkStmtListExpr, nkTypeDef, nkConstDef, nkTypeClassTy, nkObjectTy, nkRefTy, nkPtrTy, nkAsgn, nkFastAsgn, nkSinkAsgn, nkHiddenStdConv}: # notin {nkEmpty..nkNilLit, nkEnumTy, nkTupleTy}: for i in 0.. 0: + else: + result.json["description"] = %c.str + if r.buf.len > 0: result.json["code"] = %r.buf if k in routineKinds: result.json["signature"] = newJObject() @@ -1387,7 +1400,8 @@ proc generateDoc*(d: PDoc, n, orig: PNode, config: ConfigRef, docFlags: DocFlags d.modDeprecationMsg.add(genDeprecationMsg(d, pragmaNode)) let doctypeNode = findPragma(n, wDoctype) setDoctype(d, doctypeNode) - of nkCommentStmt: d.modDescPre.add(genComment(d, n)) + of nkCommentStmt: + d.modDescPre.add(genComment(d, n).get()) of nkProcDef, nkFuncDef: when useEffectSystem: documentRaises(d.cache, n) genItemAux(skProc) @@ -1427,7 +1441,7 @@ proc generateDoc*(d: PDoc, n, orig: PNode, config: ConfigRef, docFlags: DocFlags of nkExportExceptStmt: discard "transformed into nkExportStmt by semExportExcept" of nkFromStmt, nkImportExceptStmt: traceDeps(d, n[0]) of nkCallKinds: - var comm: ItemPre = default(ItemPre) + var comm = default(ItemPre) getAllRunnableExamples(d, n, comm) if comm.len != 0: d.modDescPre.add(comm) else: discard @@ -1555,7 +1569,11 @@ proc finishGenerateDoc*(d: var PDoc) = else: d.section[k].finalMarkup.add(nameContent) d.section[k].secItems.clear - renderItemPre(d, d.modDescPre, d.modDescFinal) + if optDocRaw in d.conf.globalOptions: + for item in d.modDescPre: + d.modDescFinal &= item.str + else: + renderItemPre(d, d.modDescPre, d.modDescFinal) d.modDescPre.setLen 0 # Finalize fragments of ``.json`` file @@ -1582,10 +1600,10 @@ proc generateJson*(d: PDoc, n: PNode, config: ConfigRef, includeComments: bool = setDoctype(d, doctypeNode) of nkCommentStmt: if includeComments: - d.add JsonItem(rst: genComment(d, n), rstField: "comment", + d.add JsonItem(rst: genComment(d, n).get().rst, rstField: "comment", json: %Table[string, string]()) else: - d.modDescPre.add(genComment(d, n)) + d.modDescPre.add(genComment(d, n).get()) of nkProcDef, nkFuncDef: when useEffectSystem: documentRaises(d.cache, n) d.add genJsonItem(d, n, n[namePos], skProc) diff --git a/tests/misc/trunner.nim b/tests/misc/trunner.nim index bfc54c71ad390..efa5f75b2c971 100644 --- a/tests/misc/trunner.nim +++ b/tests/misc/trunner.nim @@ -253,14 +253,13 @@ sub/mmain.idx""", context block: # nim jsondoc --raw switch let file = testsDir / "misc/mrawjson.nim" - let destdir = testsDir / "misc/rawjsondocs" - removeDir(destDir) - defer: removeDir(destDir) - let (msg, exitCode) = execCmdEx(fmt"{nim} jsondoc --raw {file}") + let output = "nimcache_tjsondoc.json" + defer: removeFile(output) + let (msg, exitCode) = execCmdEx(fmt"{nim} jsondoc --raw -o:{output} {file}") doAssert exitCode == 0, msg - let data = parseJson(readFile(destDir / "mrawjson.json")) - doAssert data["moduleDescription"].getStr == "Module description. See [someProc]" + let data = parseFile(output) + doAssert data["moduleDescription"].getStr == "Module description. See [someProc]", data["moduleDescription"].getStr let someProc = data["entries"][0] doAssert someProc["description"].getStr == "Code should be used like `someProc(1, 2)`" From 61fb45cb94c8fed37d3663ae39c89a7a5f005777 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Wed, 25 Dec 2024 21:36:03 +1100 Subject: [PATCH 06/12] Clean up code Add newline between each section --- compiler/docgen.nim | 20 +++++++------------- 1 file changed, 7 insertions(+), 13 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 4a716e671d483..982fe8124ffa5 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -113,6 +113,9 @@ type proc add(dest: var ItemPre, rst: PRstNode) = dest.add ItemFragment(isRst: true, rst: rst) proc add(dest: var ItemPre, str: string) = dest.add ItemFragment(isRst: false, str: str) +proc add(dest: var ItemPre, item: sink Option[ItemFragment]) = + if item.isSome(): + dest.add item.unsafeGet() proc addRstFileIndex(d: PDoc, fileIndex: lineinfos.FileIndex): rstast.FileIndex = let invalid = rstast.FileIndex(-1) @@ -477,14 +480,6 @@ proc genRecComment(d: PDoc, n: PNode): Option[ItemFragment] = else: result = genRecCommentAux(d, n) -proc findDocString(n: PNode): string = - result = "" - if n.comment != "": - result = n.comment - elif n.kind in {nkProcDef, nkFuncDef, nkMethodDef, nkIteratorDef, - nkMacroDef, nkTemplateDef, nkConverterDef}: - result = findDocString(n[bodyPos]) - proc getPlainDocstring(n: PNode): string = ## Gets the plain text docstring of a node non destructively. ## @@ -809,8 +804,7 @@ proc getAllRunnableExamples(d: PDoc, n: PNode, dest: var ItemPre) = template fn(n2, topLevel) = state = getAllRunnableExamplesImpl(d, n2, dest, state, topLevel) let comment = genComment(d, n) - if comment.isSome(): - dest.add genComment(d, n).unsafeGet() + dest.add genComment(d, n) case n.kind of routineDefs: n = n.getRoutineBody @@ -1075,7 +1069,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx if n.kind in routineDefs: getAllRunnableExamples(d, n, comm) else: - comm.add genRecComment(d, n).get() + comm.add genRecComment(d, n) # Obtain the plain rendered string for hyperlink titles. var r: TSrcGen = initTokRender(n, {renderNoBody, renderNoComments, renderDocComments, @@ -1184,7 +1178,6 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): JsonItem = if not isVisible(d, nameNode): return var - plainDocs = n.findDocString() name = getNameEsc(d, nameNode) comm = genRecComment(d, n) r: TSrcGen @@ -1571,7 +1564,8 @@ proc finishGenerateDoc*(d: var PDoc) = d.section[k].secItems.clear if optDocRaw in d.conf.globalOptions: for item in d.modDescPre: - d.modDescFinal &= item.str + d.modDescFinal &= item.str & '\n' + d.modDescFinal.setLen(d.modDescFinal.high) else: renderItemPre(d, d.modDescPre, d.modDescFinal) d.modDescPre.setLen 0 From 8483469f21430e69df43a81af4c6681c1e8f7530 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Wed, 25 Dec 2024 22:07:41 +1100 Subject: [PATCH 07/12] Use the optional add overload --- compiler/docgen.nim | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 982fe8124ffa5..7732443348024 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -740,7 +740,7 @@ proc getAllRunnableExamplesImpl(d: PDoc; n: PNode, dest: var ItemPre, case n.kind of nkCommentStmt: if state in {rsStart, rsRunnable}: - dest.add genRecComment(d, n).get() + dest.add genRecComment(d, n) return rsComment of nkCallKinds: if isRunnableExamples(n[0]) and From 542e3c34f90455b38cbcdd405fd888133f836f05 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Thu, 26 Dec 2024 14:19:08 +1100 Subject: [PATCH 08/12] `renderItemPre` handles dispatching for strings anyways --- compiler/docgen.nim | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 7732443348024..8bb9812d2a346 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -740,7 +740,7 @@ proc getAllRunnableExamplesImpl(d: PDoc; n: PNode, dest: var ItemPre, case n.kind of nkCommentStmt: if state in {rsStart, rsRunnable}: - dest.add genRecComment(d, n) + dest.add genRecComment(d, n).get() return rsComment of nkCallKinds: if isRunnableExamples(n[0]) and @@ -1394,7 +1394,7 @@ proc generateDoc*(d: PDoc, n, orig: PNode, config: ConfigRef, docFlags: DocFlags let doctypeNode = findPragma(n, wDoctype) setDoctype(d, doctypeNode) of nkCommentStmt: - d.modDescPre.add(genComment(d, n).get()) + d.modDescPre.add(genComment(d, n)) of nkProcDef, nkFuncDef: when useEffectSystem: documentRaises(d.cache, n) genItemAux(skProc) @@ -1562,12 +1562,7 @@ proc finishGenerateDoc*(d: var PDoc) = else: d.section[k].finalMarkup.add(nameContent) d.section[k].secItems.clear - if optDocRaw in d.conf.globalOptions: - for item in d.modDescPre: - d.modDescFinal &= item.str & '\n' - d.modDescFinal.setLen(d.modDescFinal.high) - else: - renderItemPre(d, d.modDescPre, d.modDescFinal) + renderItemPre(d, d.modDescPre, d.modDescFinal) d.modDescPre.setLen 0 # Finalize fragments of ``.json`` file From 49b818624353e8b9da0a53f114a43a7b9287a55f Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Thu, 26 Dec 2024 14:23:25 +1100 Subject: [PATCH 09/12] Be consistent --- compiler/docgen.nim | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 8bb9812d2a346..5294424c5cdc9 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -115,7 +115,7 @@ proc add(dest: var ItemPre, rst: PRstNode) = dest.add ItemFragment(isRst: true, proc add(dest: var ItemPre, str: string) = dest.add ItemFragment(isRst: false, str: str) proc add(dest: var ItemPre, item: sink Option[ItemFragment]) = if item.isSome(): - dest.add item.unsafeGet() + dest.add item.unsafeGet proc addRstFileIndex(d: PDoc, fileIndex: lineinfos.FileIndex): rstast.FileIndex = let invalid = rstast.FileIndex(-1) @@ -466,14 +466,14 @@ proc genRecCommentAux(d: PDoc, n: PNode): Option[ItemFragment] = # notin {nkEmpty..nkNilLit, nkEnumTy, nkTupleTy}: for i in 0.. Date: Thu, 26 Dec 2024 14:27:48 +1100 Subject: [PATCH 10/12] Add line into docs Add entry into changelog --- changelog.md | 2 +- compiler/options.nim | 2 +- doc/advopt.txt | 1 + 3 files changed, 3 insertions(+), 2 deletions(-) diff --git a/changelog.md b/changelog.md index 6f764791c47b4..f338a548e8725 100644 --- a/changelog.md +++ b/changelog.md @@ -69,4 +69,4 @@ errors. ## Tool changes - +- Added `--raw` flag when generating JSON docs to not render markup. diff --git a/compiler/options.nim b/compiler/options.nim index 064e3f59d06bf..51b61947b8722 100644 --- a/compiler/options.nim +++ b/compiler/options.nim @@ -110,7 +110,7 @@ type # please make sure we have under 32 options optEnableDeepCopy # ORC specific: enable 'deepcopy' for all types. optShowNonExportedFields # for documentation: show fields that are not exported optJsBigInt64 # use bigints for 64-bit integers in JS - optDocRaw # for documentation: Don't render HTML for JSON output + optDocRaw # for documentation: Don't render markdown for JSON output TGlobalOptions* = set[TGlobalOption] diff --git a/doc/advopt.txt b/doc/advopt.txt index 042c3879892a0..8442f1c1493a2 100644 --- a/doc/advopt.txt +++ b/doc/advopt.txt @@ -113,6 +113,7 @@ Advanced options: --docSeeSrcUrl:url activate 'see source' for doc command (see doc.item.seesrc in config/nimdoc.cfg) --docInternal also generate documentation for non-exported symbols + --raw doesn't render markup when generating JSON docs --lineDir:on|off generation of #line directive on|off --embedsrc:on|off embeds the original source code as comments in the generated output From da4a8cde8c7edf818b713c7270cbd2c23c0edd89 Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Thu, 26 Dec 2024 14:48:06 +1100 Subject: [PATCH 11/12] Just a final check to make sure it works with lines --- tests/misc/mrawjson.nim | 1 + tests/misc/trunner.nim | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/tests/misc/mrawjson.nim b/tests/misc/mrawjson.nim index d99e57113b9ff..d824a43a838ac 100644 --- a/tests/misc/mrawjson.nim +++ b/tests/misc/mrawjson.nim @@ -1,4 +1,5 @@ ## Module description. See [someProc] +## another line proc someProc*(a, b: int) = ## Code should be used like `someProc(1, 2)` diff --git a/tests/misc/trunner.nim b/tests/misc/trunner.nim index efa5f75b2c971..ac13bc5723a76 100644 --- a/tests/misc/trunner.nim +++ b/tests/misc/trunner.nim @@ -259,7 +259,7 @@ sub/mmain.idx""", context doAssert exitCode == 0, msg let data = parseFile(output) - doAssert data["moduleDescription"].getStr == "Module description. See [someProc]", data["moduleDescription"].getStr + doAssert data["moduleDescription"].getStr == "Module description. See [someProc]\nanother line" let someProc = data["entries"][0] doAssert someProc["description"].getStr == "Code should be used like `someProc(1, 2)`" From 9ecb42af55c22736fe00294d6ff4d27cd3e5ca8a Mon Sep 17 00:00:00 2001 From: Jake Leahy Date: Thu, 26 Dec 2024 14:53:38 +1100 Subject: [PATCH 12/12] Make help message clearer --- doc/advopt.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/advopt.txt b/doc/advopt.txt index 8442f1c1493a2..974ff8f70d658 100644 --- a/doc/advopt.txt +++ b/doc/advopt.txt @@ -113,7 +113,7 @@ Advanced options: --docSeeSrcUrl:url activate 'see source' for doc command (see doc.item.seesrc in config/nimdoc.cfg) --docInternal also generate documentation for non-exported symbols - --raw doesn't render markup when generating JSON docs + --raw turn off markup rendering for JSON docs --lineDir:on|off generation of #line directive on|off --embedsrc:on|off embeds the original source code as comments in the generated output