diff options
Diffstat (limited to 'compiler/docgen.nim')
| -rw-r--r-- | compiler/docgen.nim | 75 |
1 files changed, 41 insertions, 34 deletions
diff --git a/compiler/docgen.nim b/compiler/docgen.nim index 6a78d8693..8e5f5e4e7 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -15,15 +15,16 @@ ## For corresponding users' documentation see [Nim DocGen Tools Guide]. import - ast, strutils, strtabs, algorithm, sequtils, options, msgs, os, idents, + ast, options, msgs, idents, wordrecg, syntaxes, renderer, lexer, packages/docutils/[rst, rstidx, rstgen, dochelpers], - json, xmltree, trees, types, - typesrenderer, astalgo, lineinfos, intsets, - pathutils, tables, nimpaths, renderverbatim, osproc, packages + trees, types, + typesrenderer, astalgo, lineinfos, + pathutils, nimpaths, renderverbatim, packages import packages/docutils/rstast except FileIndex, TLineInfo -from uri import encodeUrl +import std/[os, strutils, strtabs, algorithm, json, osproc, tables, intsets, xmltree, sequtils] +from std/uri import encodeUrl from nodejs import findNodeJs when defined(nimPreviewSlimSystem): @@ -288,7 +289,7 @@ template declareClosures(currentFilename: AbsoluteFile, destFile: string) = let outDirPath: RelativeFile = presentationPath(conf, AbsoluteFile(basedir / targetRelPath)) # use presentationPath because `..` path can be be mangled to `_._` - result.targetPath = string(conf.outDir / outDirPath) + result = (string(conf.outDir / outDirPath), "") if not fileExists(result.targetPath): # this can happen if targetRelPath goes to parent directory `OUTDIR/..`. # Trying it, this may cause ambiguities, but allows us to insert @@ -348,7 +349,7 @@ proc newDocumentor*(filename: AbsoluteFile; cache: IdentCache; conf: ConfigRef, if conf.configVars.hasKey("doc.googleAnalytics") and conf.configVars.hasKey("doc.plausibleAnalytics"): - doAssert false, "Either use googleAnalytics or plausibleAnalytics" + raiseAssert "Either use googleAnalytics or plausibleAnalytics" if conf.configVars.hasKey("doc.googleAnalytics"): result.analytics = """ @@ -373,7 +374,7 @@ proc newDocumentor*(filename: AbsoluteFile; cache: IdentCache; conf: ConfigRef, result.seenSymbols = newStringTable(modeCaseInsensitive) result.id = 100 result.jEntriesFinal = newJArray() - initStrTable result.types + result.types = initStrTable() result.onTestSnippet = proc (gen: var RstGenerator; filename, cmd: string; status: int; content: string) {.gcsafe.} = if conf.docCmd == docCmdSkip: return @@ -830,7 +831,7 @@ proc getName(n: PNode): string = result = "`" for i in 0..<n.len: result.add(getName(n[i])) result = "`" - of nkOpenSymChoice, nkClosedSymChoice: + of nkOpenSymChoice, nkClosedSymChoice, nkOpenSym: result = getName(n[0]) else: result = "" @@ -848,7 +849,7 @@ proc getNameIdent(cache: IdentCache; n: PNode): PIdent = var r = "" for i in 0..<n.len: r.add(getNameIdent(cache, n[i]).s) result = getIdent(cache, r) - of nkOpenSymChoice, nkClosedSymChoice: + of nkOpenSymChoice, nkClosedSymChoice, nkOpenSym: result = getNameIdent(cache, n[0]) else: result = nil @@ -862,7 +863,7 @@ proc getRstName(n: PNode): PRstNode = of nkAccQuoted: result = getRstName(n[0]) for i in 1..<n.len: result.text.add(getRstName(n[i]).text) - of nkOpenSymChoice, nkClosedSymChoice: + of nkOpenSymChoice, nkClosedSymChoice, nkOpenSym: result = getRstName(n[0]) else: result = nil @@ -954,8 +955,7 @@ proc genDeprecationMsg(d: PDoc, n: PNode): string = else: result = "" else: - result = "" - doAssert false + raiseAssert "unreachable" type DocFlags = enum kDefault @@ -1000,8 +1000,9 @@ proc getTypeKind(n: PNode): string = proc toLangSymbol(k: TSymKind, n: PNode, baseName: string): LangSymbol = ## Converts symbol info (names/types/parameters) in `n` into format ## `LangSymbol` convenient for ``rst.nim``/``dochelpers.nim``. - result.name = baseName.nimIdentNormalize - result.symKind = k.toHumanStr + result = LangSymbol(name: baseName.nimIdentNormalize, + symKind: k.toHumanStr + ) if k in routineKinds: var paramTypes: seq[string] = @[] @@ -1030,7 +1031,7 @@ proc toLangSymbol(k: TSymKind, n: PNode, baseName: string): LangSymbol = if genNode != nil: var literal = "" var r: TSrcGen = initTokRender(genNode, {renderNoBody, renderNoComments, - renderNoPragmas, renderNoProcDefs, renderExpandUsing}) + renderNoPragmas, renderNoProcDefs, renderExpandUsing, renderNoPostfix}) var kind = tkEof while true: getNextTok(r, kind, literal) @@ -1058,7 +1059,7 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx # Obtain the plain rendered string for hyperlink titles. var r: TSrcGen = initTokRender(n, {renderNoBody, renderNoComments, renderDocComments, - renderNoPragmas, renderNoProcDefs, renderExpandUsing}) + renderNoPragmas, renderNoProcDefs, renderExpandUsing, renderNoPostfix}) while true: getNextTok(r, kind, literal) if kind == tkEof: @@ -1085,6 +1086,9 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx symbolOrIdEnc = encodeUrl(symbolOrId, usePlus = false) deprecationMsg = genDeprecationMsg(d, pragmaNode) rstLangSymbol = toLangSymbol(k, n, cleanPlainSymbol) + symNameNode = + if nameNode.kind == nkPostfix: nameNode[1] + else: nameNode # we generate anchors automatically for subsequent use in doc comments let lineinfo = rstast.TLineInfo( @@ -1095,10 +1099,10 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx priority = symbolPriority(k), info = lineinfo, module = addRstFileIndex(d, FileIndex d.module.position)) - let renderFlags = - if nonExports: {renderNoBody, renderNoComments, renderDocComments, renderSyms, - renderExpandUsing, renderNonExportedFields} - else: {renderNoBody, renderNoComments, renderDocComments, renderSyms, renderExpandUsing} + var renderFlags = {renderNoBody, renderNoComments, renderDocComments, + renderSyms, renderExpandUsing, renderNoPostfix} + if nonExports: + renderFlags.incl renderNonExportedFields nodeToHighlightedHtml(d, n, result, renderFlags, symbolOrIdEnc) let seeSrc = genSeeSrc(d, toFullPath(d.conf, n.info), n.info.line.int) @@ -1121,18 +1125,19 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx let external = d.destFile.AbsoluteFile.relativeTo(d.conf.outDir, '/').changeFileExt(HtmlExt).string var attype = "" - if k in routineKinds and nameNode.kind == nkSym: + if k in routineKinds and symNameNode.kind == nkSym: let att = attachToType(d, nameNode.sym) if att != nil: attype = esc(d.target, att.name.s) - elif k == skType and nameNode.kind == nkSym and nameNode.sym.typ.kind in {tyEnum, tyBool}: - let etyp = nameNode.sym.typ + elif k == skType and symNameNode.kind == nkSym and + symNameNode.sym.typ.kind in {tyEnum, tyBool}: + let etyp = symNameNode.sym.typ for e in etyp.n: if e.sym.kind != skEnumField: continue let plain = renderPlainSymbolName(e) let symbolOrId = d.newUniquePlainSymbol(plain) setIndexTerm(d[], ieNim, htmlFile = external, id = symbolOrId, - term = plain, linkTitle = nameNode.sym.name.s & '.' & plain, + term = plain, linkTitle = symNameNode.sym.name.s & '.' & plain, linkDesc = xmltree.escape(getPlainDocstring(e).docstringSummary), line = n.info.line.int) @@ -1153,8 +1158,8 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonEx linkTitle = detailedName, linkDesc = xmltree.escape(plainDocstring.docstringSummary), line = n.info.line.int) - if k == skType and nameNode.kind == nkSym: - d.types.strTableAdd nameNode.sym + if k == skType and symNameNode.kind == nkSym: + d.types.strTableAdd symNameNode.sym proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): JsonItem = if not isVisible(d, nameNode): return @@ -1162,12 +1167,14 @@ proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): name = getNameEsc(d, nameNode) comm = genRecComment(d, n) r: TSrcGen - renderFlags = {renderNoBody, renderNoComments, renderDocComments, renderExpandUsing} + renderFlags = {renderNoBody, renderNoComments, renderDocComments, + renderExpandUsing, renderNoPostfix} if nonExports: renderFlags.incl renderNonExportedFields r = initTokRender(n, renderFlags) - result.json = %{ "name": %name, "type": %($k), "line": %n.info.line.int, + result = JsonItem(json: %{ "name": %name, "type": %($k), "line": %n.info.line.int, "col": %n.info.col} + ) if comm != nil: result.rst = comm result.rstField = "description" @@ -1197,10 +1204,9 @@ proc genJsonItem(d: PDoc, n, nameNode: PNode, k: TSymKind, nonExports = false): result.json["signature"]["genericParams"] = newJArray() for genericParam in n[genericParamsPos]: var param = %{"name": %($genericParam)} - if genericParam.sym.typ.sons.len > 0: + if genericParam.sym.typ.len > 0: param["types"] = newJArray() - for kind in genericParam.sym.typ.sons: - param["types"].add %($kind) + param["types"] = %($genericParam.sym.typ.elementType) result.json["signature"]["genericParams"].add param if optGenIndex in d.conf.globalOptions: genItem(d, n, nameNode, k, kForceExport) @@ -1400,7 +1406,8 @@ proc generateDoc*(d: PDoc, n, orig: PNode, config: ConfigRef, docFlags: DocFlags for it in n: traceDeps(d, it) of nkExportStmt: for it in n: - if it.kind == nkSym: + # bug #23051; don't generate documentation for exported symbols again + if it.kind == nkSym and sfExported notin it.sym.flags: if d.module != nil and d.module == it.sym.owner: generateDoc(d, it.sym.ast, orig, config, kForceExport) elif it.sym.ast != nil: @@ -1806,7 +1813,7 @@ proc writeOutputJson*(d: PDoc, useWarning = false) = "moduleDescription": modDesc, "entries": d.jEntriesFinal} if optStdout in d.conf.globalOptions: - write(stdout, $content) + writeLine(stdout, $content) else: let dir = d.destFile.splitFile.dir createDir(dir) |