jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

fixes #19396; Nimdoc hide nonexported fields (#21305)

Browse source 
* suppresses non-exported fields of types and adds command-line option to re-enable this if desired

* corrected the doctest that produced a CI error

* an embarrassingly bad error in reasoning

* modified a nimdoc test to reflect updated behavior

* needed another change to bring utils.html doctest in sync with update

* add info

* fix nimdoc

* lint

* render postfix

* fixes a problem

* fixes nimdoc

* fix nimdoc

---------

Co-authored-by: johnperry-math <john.perry@usm.edu>
Co-authored-by: johnperry-math <devotus@yahoo.com>
This commit is contained in:
ringabout 2023-02-01 15:13:40 +08:00 • committed by GitHub
commit ff8ab06720
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
13 changed files with 56 additions and 24 deletions
Download patch file Download diff file Expand all files Collapse all files

22
compiler/docgen.nim
View file

@ -1008,7 +1008,7 @@ proc toLangSymbol(k: TSymKind, n: PNode, baseName: string): LangSymbol =
if k == skType: result.symTypeKind = getTypeKind(n)
proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) =
proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags, nonExports: bool = false) =
if (docFlags != kForceExport) and not isVisible(d, nameNode): return
let
name = getName(nameNode)
@ -1062,8 +1062,11 @@ proc genItem(d: PDoc, n, nameNode: PNode, k: TSymKind, docFlags: DocFlags) =
tooltip = detailedName, langSym = rstLangSymbol,
priority = symbolPriority(k), info = lineinfo)
nodeToHighlightedHtml(d, n, result, {renderNoBody, renderNoComments,
renderDocComments, renderSyms, renderExpandUsing}, symbolOrIdEnc)
let renderFlags =
if nonExports: {renderNoBody, renderNoComments, renderDocComments, renderSyms,
renderExpandUsing, renderNonExportedFields}
else: {renderNoBody, renderNoComments, renderDocComments, renderSyms, renderExpandUsing}
nodeToHighlightedHtml(d, n, result, renderFlags, symbolOrIdEnc)
let seeSrc = genSeeSrc(d, toFullPath(d.conf, n.info), n.info.line.int)
@ -1311,12 +1314,13 @@ proc documentRaises*(cache: IdentCache; n: PNode) =
if p5 != nil: n[pragmasPos].add p5
if p6 != nil: n[pragmasPos].add p6
proc generateDoc*(d: PDoc, n, orig: PNode, docFlags: DocFlags = kDefault) =
proc generateDoc*(d: PDoc, n, orig: PNode, config: ConfigRef, docFlags: DocFlags = kDefault) =
## Goes through nim nodes recursively and collects doc comments.
## Main function for `doc`:option: command,
## which is implemented in ``docgen2.nim``.
template genItemAux(skind) =
genItem(d, n, n[namePos], skind, docFlags)
let showNonExports = optShowNonExportedFields in config.globalOptions
case n.kind
of nkPragma:
let pragmaNode = findPragma(n, wDeprecated)
@ -1343,20 +1347,20 @@ proc generateDoc*(d: PDoc, n, orig: PNode, docFlags: DocFlags = kDefault) =
if n[i].kind != nkCommentStmt:
# order is always 'type var let const':
genItem(d, n[i], n[i][0],
succ(skType, ord(n.kind)-ord(nkTypeSection)), docFlags)
succ(skType, ord(n.kind)-ord(nkTypeSection)), docFlags, showNonExports)
of nkStmtList:
for i in 0..<n.len: generateDoc(d, n[i], orig)
for i in 0..<n.len: generateDoc(d, n[i], orig, config)
of nkWhenStmt:
# generate documentation for the first branch only:
if not checkForFalse(n[0][0]):
generateDoc(d, lastSon(n[0]), orig)
generateDoc(d, lastSon(n[0]), orig, config)
of nkImportStmt:
for it in n: traceDeps(d, it)
of nkExportStmt:
for it in n:
if it.kind == nkSym:
if d.module != nil and d.module == it.sym.owner:
generateDoc(d, it.sym.ast, orig, kForceExport)
generateDoc(d, it.sym.ast, orig, config, kForceExport)
elif it.sym.ast != nil:
exportSym(d, it.sym)
of nkExportExceptStmt: discard "transformed into nkExportStmt by semExportExcept"
@ -1786,7 +1790,7 @@ proc commandDoc*(cache: IdentCache, conf: ConfigRef) =
var ast = parseFile(conf.projectMainIdx, cache, conf)
if ast == nil: return
var d = newDocumentor(conf.projectFull, cache, conf, hasToc = true)
generateDoc(d, ast, ast)
generateDoc(d, ast, ast, conf)
finishGenerateDoc(d)
writeOutput(d)
generateIndex(d)