From a7bb973a24fb73d378230216a6bfcfd2f62e4e78 Mon Sep 17 00:00:00 2001 From: Timothee Cour Date: Wed, 31 Mar 2021 23:45:55 -0700 Subject: [PATCH] docgen: render pragmas by default except for a select list (and fix #9074) (#17054) --- compiler/docgen.nim | 22 ++--- compiler/lexer.nim | 2 +- compiler/renderer.nim | 22 ++++- .../expected/index.html | 2 +- .../expected/subdir/subdir_b/utils.html | 2 +- nimdoc/testproject/expected/testproject.html | 82 +++++++++---------- 6 files changed, 76 insertions(+), 56 deletions(-) diff --git a/compiler/docgen.nim b/compiler/docgen.nim index f1a9750b71..67f21e1c4d 100644 --- a/compiler/docgen.nim +++ b/compiler/docgen.nim @@ -446,22 +446,22 @@ proc nodeToHighlightedHtml(d: PDoc; n: PNode; result: var Rope; renderFlags: TRe "\\spanIdentifier{$1}", [escLit]) of tkSpaces, tkInvalid: result.add(literal) - of tkCurlyDotLe: + of tkHideableStart: template fun(s) = dispA(d.conf, result, s, "\\spanOther{$1}", [escLit]) if renderRunnableExamples in renderFlags: fun "$1" - else: fun: "" & # This span is required for the JS to work properly - """{...} + else: + # 1st span is required for the JS to work properly + fun """ + +... - -$1 -""".replace("\n", "") # Must remove newlines because wrapped in a 
-    of tkCurlyDotRi:
+""".replace("\n", "")  # Must remove newlines because wrapped in a 
+    of tkHideableEnd:
       template fun(s) = dispA(d.conf, result, s, "\\spanOther{$1}", [escLit])
       if renderRunnableExamples in renderFlags: fun "$1"
-      else: fun """
-
-$1
-""".replace("\n", "")
+      else: fun ""
+    of tkCurlyDotLe: dispA(d.conf, result, "$1", "\\spanOther{$1}", [escLit])
+    of tkCurlyDotRi: dispA(d.conf, result, "$1", "\\spanOther{$1}", [escLit])
     of tkParLe, tkParRi, tkBracketLe, tkBracketRi, tkCurlyLe, tkCurlyRi,
        tkBracketDotLe, tkBracketDotRi, tkParDotLe,
        tkParDotRi, tkComma, tkSemiColon, tkColon, tkEquals, tkDot, tkDotDot,
diff --git a/compiler/lexer.nim b/compiler/lexer.nim
index cca7765e57..7c7ac41776 100644
--- a/compiler/lexer.nim
+++ b/compiler/lexer.nim
@@ -72,7 +72,7 @@ type
     tkDot = ".", tkDotDot = "..", tkBracketLeColon = "[:",
     tkOpr, tkComment, tkAccent = "`",
     # these are fake tokens used by renderer.nim
-    tkSpaces, tkInfixOpr, tkPrefixOpr, tkPostfixOpr
+    tkSpaces, tkInfixOpr, tkPrefixOpr, tkPostfixOpr, tkHideableStart, tkHideableEnd
 
   TokTypes* = set[TokType]
 
diff --git a/compiler/renderer.nim b/compiler/renderer.nim
index b9ec481853..3d260f350a 100644
--- a/compiler/renderer.nim
+++ b/compiler/renderer.nim
@@ -185,7 +185,7 @@ proc dedent(g: var TSrcGen) =
 proc put(g: var TSrcGen, kind: TokType, s: string; sym: PSym = nil) =
   if kind != tkSpaces:
     addPendingNL(g)
-    if s.len > 0:
+    if s.len > 0 or kind in {tkHideableStart, tkHideableEnd}:
       addTok(g, kind, s, sym)
   else:
     g.pendingWhitespace = s.len
@@ -587,13 +587,30 @@ proc putWithSpace(g: var TSrcGen, kind: TokType, s: string) =
   put(g, kind, s)
   put(g, tkSpaces, Space)
 
+proc isHideable(config: ConfigRef, n: PNode): bool =
+  # xxx compare `ident` directly with `getIdent(cache, wRaises)`, but
+  # this requires a `cache`.
+  case n.kind
+  of nkExprColonExpr: result = n[0].kind == nkIdent and n[0].ident.s in ["raises", "tags", "extern"]
+  of nkIdent: result = n.ident.s in ["gcsafe"]
+  else: result = false
+
 proc gcommaAux(g: var TSrcGen, n: PNode, ind: int, start: int = 0,
                theEnd: int = - 1, separator = tkComma) =
+  let inPragma = g.inPragma == 1 # just the top-level
+  var inHideable = false
   for i in start..n.len + theEnd:
     var c = i < n.len + theEnd
     var sublen = lsub(g, n[i]) + ord(c)
     if not fits(g, g.lineLen + sublen) and (ind + sublen < MaxLineLen): optNL(g, ind)
     let oldLen = g.tokens.len
+    if inPragma:
+      if not inHideable and isHideable(g.config, n[i]):
+        inHideable = true
+        put(g, tkHideableStart, "")
+      elif inHideable and not isHideable(g.config, n[i]):
+        inHideable = false
+        put(g, tkHideableEnd, "")
     gsub(g, n[i])
     if c:
       if g.tokens.len > oldLen:
@@ -601,6 +618,9 @@ proc gcommaAux(g: var TSrcGen, n: PNode, ind: int, start: int = 0,
       if shouldRenderComment(g) and hasCom(n[i]):
         gcoms(g)
         optNL(g, ind)
+  if inHideable:
+    put(g, tkHideableEnd, "")
+    inHideable = false
 
 proc gcomma(g: var TSrcGen, n: PNode, c: TContext, start: int = 0,
             theEnd: int = - 1) =
diff --git a/nimdoc/test_out_index_dot_html/expected/index.html b/nimdoc/test_out_index_dot_html/expected/index.html
index db74700508..bac39fd33b 100644
--- a/nimdoc/test_out_index_dot_html/expected/index.html
+++ b/nimdoc/test_out_index_dot_html/expected/index.html
@@ -117,7 +117,7 @@ window.addEventListener('DOMContentLoaded', main);
 
Procs

 

 
-
proc foo() {...}{.raises: [], tags: [].}

+
proc foo() {....raises: [], tags: [].}

 

 
 I do foo
diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
index cb80f2873c..c1ee9c49d5 100644
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
@@ -177,7 +177,7 @@ window.addEventListener('DOMContentLoaded', main);
 
Procs

 

 
-
proc someType(): SomeType {...}{.raises: [], tags: [].}

+
proc someType(): SomeType {....raises: [], tags: [].}

 

 
 constructor.
diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index 599a904a2d..8525048eac 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -444,7 +444,7 @@ window.addEventListener('DOMContentLoaded', main);
 
Types

 

 
-
A {...}{.inject.} = enum
+
A {.inject.} = enum
   aA

 

 
@@ -452,7 +452,7 @@ The enum A.
 
 

 
-
B {...}{.inject.} = enum
+
B {.inject.} = enum
   bB

 

 
@@ -542,7 +542,7 @@ This should be visible.
 
 

 
-
proc baz[T](a, b: T): T {...}{.deprecated.}

+
proc baz[T](a, b: T): T {.deprecated.}

 

   

     Deprecated 
@@ -552,7 +552,7 @@ This is deprecated without message.
 
 

 
-
proc buzz[T](a, b: T): T {...}{.deprecated: "since v0.20".}

+
proc buzz[T](a, b: T): T {.deprecated: "since v0.20".}

 

   

     Deprecated: since v0.20
@@ -562,14 +562,14 @@ This is deprecated with a message.
 
 

 
-
func someFunc() {...}{.raises: [], tags: [].}

+
func someFunc() {....raises: [], tags: [].}

 

 
 My someFunc. Stuff in quotes here. Some link
 
 

 
-
proc fromUtils3() {...}{.raises: [], tags: [].}

+
proc fromUtils3() {....raises: [], tags: [].}

 

 
 came form utils but should be shown where fromUtilsGen is called
@@ -585,14 +585,14 @@ came form utils but should be shown where 
 
-
proc z1(): Foo {...}{.raises: [], tags: [].}

+
proc z1(): Foo {....raises: [], tags: [].}

 

 
 cz1
 
 

 
-
proc z2() {...}{.raises: [], tags: [].}

+
proc z2() {....raises: [], tags: [].}

 

 
 cz2
@@ -601,49 +601,49 @@ cz2
 
 

 
-
proc z3() {...}{.raises: [], tags: [].}

+
proc z3() {....raises: [], tags: [].}

 

 
 cz3
 
 

 
-
proc z4() {...}{.raises: [], tags: [].}

+
proc z4() {....raises: [], tags: [].}

 

 
 cz4
 
 

 
-
proc z5(): int {...}{.raises: [], tags: [].}

+
proc z5(): int {....raises: [], tags: [].}

 

 
 cz5
 
 

 
-
proc z6(): int {...}{.raises: [], tags: [].}

+
proc z6(): int {....raises: [], tags: [].}

 

 
 cz6
 
 

 
-
proc z7(): int {...}{.raises: [], tags: [].}

+
proc z7(): int {....raises: [], tags: [].}

 

 
 cz7
 
 

 
-
proc z8(): int {...}{.raises: [], tags: [].}

+
proc z8(): int {....raises: [], tags: [].}

 

 
 cz8
 
 

 
-
proc z9() {...}{.raises: [], tags: [].}

+
proc z9() {....raises: [], tags: [].}

 

 
 
@@ -652,7 +652,7 @@ cz8
 
 

 
-
proc z10() {...}{.raises: [], tags: [].}

+
proc z10() {....raises: [], tags: [].}

 

 
 
@@ -661,7 +661,7 @@ cz8
 
 

 
-
proc z11() {...}{.raises: [], tags: [].}

+
proc z11() {....raises: [], tags: [].}

 

 
 
@@ -670,7 +670,7 @@ cz8
 
 

 
-
proc z12(): int {...}{.raises: [], tags: [].}

+
proc z12(): int {....raises: [], tags: [].}

 

 
 
@@ -679,7 +679,7 @@ cz8
 
 

 
-
proc z13() {...}{.raises: [], tags: [].}

+
proc z13() {....raises: [], tags: [].}

 

 
 cz13
@@ -688,14 +688,14 @@ cz13
 
 

 
-
proc baz() {...}{.raises: [], tags: [].}

+
proc baz() {....raises: [], tags: [].}

 

 
 
 
 

 
-
proc z17() {...}{.raises: [], tags: [].}

+
proc z17() {....raises: [], tags: [].}

 

 
 cz17 rest
@@ -704,7 +704,7 @@ cz17 rest
 
 

 
-
proc p1() {...}{.raises: [], tags: [].}

+
proc p1() {....raises: [], tags: [].}

 

 
 cp1
@@ -727,7 +727,7 @@ this is a nested doc comment
 
 

 
-
proc addfBug14485() {...}{.raises: [], tags: [].}

+
proc addfBug14485() {....raises: [], tags: [].}

 

 
 Some proc
@@ -746,23 +746,23 @@ Some proc
 
 

 
-
proc c_printf(frmt: cstring): cint {...}{.importc: "printf", header: "<stdio.h>",
-                                     varargs, discardable.}

+
proc c_printf(frmt: cstring): cint {.importc: "printf", header: "<stdio.h>",
+                                     varargs, discardable.}

 

 
 the c printf. etc.
 
 

 
-
proc c_nonexistant(frmt: cstring): cint {...}{.importc: "nonexistant",
-    header: "<stdio.h>", varargs, discardable.}

+
proc c_nonexistant(frmt: cstring): cint {.importc: "nonexistant",
+    header: "<stdio.h>", varargs, discardable.}

 

 
 
 
 

 
-
proc low[T: Ordinal | enum | range](x: T): T {...}{.magic: "Low", noSideEffect.}

+
proc low[T: Ordinal | enum | range](x: T): T {.magic: "Low", noSideEffect.}

 

 
 
Returns the lowest possible value of an ordinal value x. As a special semantic rule, x may also be a type identifier.

@@ -773,7 +773,7 @@ the c printf. etc.
 
 

 
-
proc low2[T: Ordinal | enum | range](x: T): T {...}{.magic: "Low", noSideEffect.}

+
proc low2[T: Ordinal | enum | range](x: T): T {.magic: "Low", noSideEffect.}

 

 
 
Returns the lowest possible value of an ordinal value x. As a special semantic rule, x may also be a type identifier.

@@ -786,7 +786,7 @@ the c printf. etc.
 
 

 
-
proc tripleStrLitTest() {...}{.raises: [], tags: [].}

+
proc tripleStrLitTest() {....raises: [], tags: [].}

 

 
 
@@ -829,22 +829,22 @@ at indent 0
 
 

 
-
proc asyncFun1(): Future[int] {...}{.raises: [Exception, ValueError],
-                                tags: [RootEffect].}

+
proc asyncFun1(): Future[int] {....raises: [Exception, ValueError],
+                                tags: [RootEffect].}

 

 
 ok1
 
 

 
-
proc asyncFun2(): owned(Future[void]) {...}{.raises: [Exception], tags: [RootEffect].}

+
proc asyncFun2(): owned(Future[void]) {....raises: [Exception], tags: [RootEffect].}

 

 
 
 
 

 
-
proc asyncFun3(): owned(Future[void]) {...}{.raises: [Exception], tags: [RootEffect].}

+
proc asyncFun3(): owned(Future[void]) {....raises: [Exception], tags: [RootEffect].}

 

 
 
@@ -853,7 +853,7 @@ ok1
 
 

 
-
proc anything() {...}{.raises: [], tags: [].}

+
proc anything() {....raises: [], tags: [].}

 

 
 There is no block quote after blank lines at the beginning.
@@ -865,21 +865,21 @@ There is no block quote after blank lines at the beginning.
 
Methods

 

 
-
method method1(self: Moo) {...}{.raises: [], tags: [].}

+
method method1(self: Moo) {....raises: [], tags: [].}

 

 
 foo1
 
 

 
-
method method2(self: Moo): int {...}{.raises: [], tags: [].}

+
method method2(self: Moo): int {....raises: [], tags: [].}

 

 
 foo2
 
 

 
-
method method3(self: Moo): int {...}{.raises: [], tags: [].}

+
method method3(self: Moo): int {....raises: [], tags: [].}

 

 
 foo3
@@ -891,7 +891,7 @@ foo3
 
Iterators

 

 
-
iterator fromUtils1(): int {...}{.raises: [], tags: [].}

+
iterator fromUtils1(): int {....raises: [], tags: [].}

 

 
 
@@ -902,14 +902,14 @@ foo3
 
 

 
-
iterator iter1(n: int): int {...}{.raises: [], tags: [].}

+
iterator iter1(n: int): int {....raises: [], tags: [].}

 

 
 foo1
 
 

 
-
iterator iter2(n: int): int {...}{.raises: [], tags: [].}

+
iterator iter2(n: int): int {....raises: [], tags: [].}

 

 
 foo2