From ff8ab06720976f18d75257a22bf8e23873514c67 Mon Sep 17 00:00:00 2001 From: ringabout <43030857+ringabout@users.noreply.github.com> Date: Wed, 1 Feb 2023 15:13:40 +0800 Subject: fixes #19396; Nimdoc hide nonexported fields (#21305) * 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 Co-authored-by: johnperry-math --- compiler/commands.nim | 3 +++ compiler/docgen.nim | 22 +++++++++++++--------- compiler/docgen2.nim | 2 +- compiler/options.nim | 4 ++++ compiler/renderer.nim | 13 ++++++++----- compiler/vm.nim | 2 +- doc/docgen.md | 1 + nimdoc/extlinks/project/expected/main.html | 6 ++---- .../expected/subdir/subdir_b/utils.html | 6 ++---- nimdoc/testproject/expected/testproject.html | 12 ++++++++++++ nimdoc/testproject/expected/testproject.idx | 1 + nimdoc/testproject/expected/theindex.html | 4 ++++ nimdoc/testproject/testproject.nim | 4 ++++ 13 files changed, 56 insertions(+), 24 deletions(-) diff --git a/compiler/commands.nim b/compiler/commands.nim index 59b221647..7c0f7ab0a 100644 --- a/compiler/commands.nim +++ b/compiler/commands.nim @@ -1008,6 +1008,9 @@ proc processSwitch*(switch, arg: string, pass: TCmdLinePass, info: TLineInfo; expectNoArg(conf, switch, arg, pass, info) conf.exc = low(ExceptionSystem) defineSymbol(conf.symbols, "noCppExceptions") + of "shownonexports": + expectNoArg(conf, switch, arg, pass, info) + showNonExportedFields(conf) of "exceptions": case arg.normalize of "cpp": conf.exc = excCpp diff --git a/compiler/docgen.nim b/compiler/docgen.nim index cab334e7a..8105cc807 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -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.. Types @@ -97,8 +96,7 @@ 
A = object
-  x: int
-
+
diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html index f0f30536f..ee2618ab3 100644 --- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html +++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html @@ -59,8 +59,7 @@
Types
    -
  • G
    • +
  • G
  • SomeType
    • @@ -254,8 +253,7 @@ Ref. 
    G[T] = object
-  val: T
-
    +
    diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html index 7d10d7900..45a53bb93 100644 --- a/nimdoc/testproject/expected/testproject.html +++ b/nimdoc/testproject/expected/testproject.html @@ -65,6 +65,8 @@ Circle, ## A circle Triangle, ## A three-sided shape Rectangle ## A four-sided shape">Shapes +
  • T19396
@@ -399,6 +401,16 @@ Some shapes. +
+
+
+ 
T19396 = object
+  a*: int
+
+
+ + +
diff --git a/nimdoc/testproject/expected/testproject.idx b/nimdoc/testproject/expected/testproject.idx index e69bedf33..46ffaee72 100644 --- a/nimdoc/testproject/expected/testproject.idx +++ b/nimdoc/testproject/expected/testproject.idx @@ -63,5 +63,6 @@ nim Triangle testproject.html#Triangle Shapes.Triangle 380 nim Rectangle testproject.html#Rectangle Shapes.Rectangle 380 nim Shapes testproject.html#Shapes enum Shapes 380 nim anything testproject.html#anything proc anything() 387 +nim T19396 testproject.html#T19396 object T19396 392 nimgrp bar testproject.html#bar-procs-all proc 31 nimgrp baz testproject.html#baz-procs-all proc 34 diff --git a/nimdoc/testproject/expected/theindex.html b/nimdoc/testproject/expected/theindex.html index 7b4a95561..f9488eb2d 100644 --- a/nimdoc/testproject/expected/theindex.html +++ b/nimdoc/testproject/expected/theindex.html @@ -308,6 +308,10 @@
  • testproject: var someVariable
    • +
    T19396:
    testNimDocTrailingExample:
    • testproject: template testNimDocTrailingExample()
      • diff --git a/nimdoc/testproject/testproject.nim b/nimdoc/testproject/testproject.nim index d236552ac..b5fa2ac37 100644 --- a/nimdoc/testproject/testproject.nim +++ b/nimdoc/testproject/testproject.nim @@ -388,3 +388,7 @@ when true: # issue #15184 ## ## There is no block quote after blank lines at the beginning. discard + +type T19396* = object # bug #19396 + a*: int + b: float -- cgit 1.4.1-2-gfad0