fix #9102 docgen: sidebar now shows proc signatures instead of encoding (#16857)

.gitignore

@@ -100,3 +100,5 @@ htmldocs
 
 ## these are not needed anymore unless checkout old older versions
 nimdoc.out.css
+# except here:
+!/nimdoc/testproject/expected/*

config/nimdoc.cfg

@@ -34,7 +34,8 @@ doc.section.toc2 = """
 # Available variables are:
 # * $desc: the actual docstring of the item.
 # * $header: the full version of name, including types, pragmas, tags, etc.
-# * $header_plain: like header but without HTML, for attribute embedding.
+# * $header_plain: like header but without HTML (and without pragmas, tags, etc.),
+#   for attribute embedding.
 # * $itemID: numerical unique entry of the item in the HTML.
 # * $itemSym: short symbolic name of the item for easier hyperlinking.
 # * $itemSymEnc: quoted version for URLs or attributes.
@@ -55,6 +56,9 @@ $seeSrc
 
 # Chunk of HTML emitted for each entry in the HTML table of contents.
 # See doc.item for available substitution variables.
+
+# This is used for TOC items which are not overloadable (e.g. types).
+# `$header_plain` would be too verbose here, so we use $name.
 doc.item.toc = """
   <li><a class="reference" href="#$itemSymOrIDEnc"
     title="$header_plain">$name</a></li>
@@ -63,7 +67,7 @@ doc.item.toc = """
 # This is used for TOC items which are grouped by the same name (e.g. procs).
 doc.item.tocTable = """
   <li><a class="reference" href="#$itemSymOrIDEnc"
-    title="$header_plain">$itemSymOrID</a></li>
+    title="$header_plain">$header_plain</a></li>
 """
 
 

nimdoc/test_out_index_dot_html/expected/index.html

@@ -98,7 +98,7 @@ window.addEventListener('DOMContentLoaded', main);
   <ul class="simple simple-toc-section">
       <ul class="simple nested-toc-section">foo
       <li><a class="reference" href="#foo"
-    title="foo()">foo</a></li>
+    title="foo()">foo()</a></li>
 
   </ul>
 

nimdoc/tester.nim

@@ -1,5 +1,5 @@
 # Small program that runs the test cases for 'nim doc'.
-# To run this, cd to the git repo root, and run "nim c -r nimdoc/tester.nim".
+# To run this, cd to the git repo root, and run "nim r nimdoc/tester.nim".
 # to change expected results (after carefully verifying everything), use -d:fixup
 
 import strutils, os

nimdoc/testproject/expected/subdir/subdir_b/utils.html

@@ -112,7 +112,7 @@ window.addEventListener('DOMContentLoaded', main);
   <ul class="simple simple-toc-section">
       <ul class="simple nested-toc-section">someType
       <li><a class="reference" href="#someType_2"
-    title="someType(): SomeType">someType_2</a></li>
+    title="someType(): SomeType">someType(): SomeType</a></li>
 
   </ul>
 

nimdoc/testproject/expected/testproject.html

@@ -148,159 +148,159 @@ window.addEventListener('DOMContentLoaded', main);
   <ul class="simple simple-toc-section">
       <ul class="simple nested-toc-section">z10
       <li><a class="reference" href="#z10"
-    title="z10()">z10</a></li>
+    title="z10()">z10()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">tripleStrLitTest
       <li><a class="reference" href="#tripleStrLitTest"
-    title="tripleStrLitTest()">tripleStrLitTest</a></li>
+    title="tripleStrLitTest()">tripleStrLitTest()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z17
       <li><a class="reference" href="#z17"
-    title="z17()">z17</a></li>
+    title="z17()">z17()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">asyncFun3
       <li><a class="reference" href="#asyncFun3"
-    title="asyncFun3(): owned(Future[void])">asyncFun3</a></li>
+    title="asyncFun3(): owned(Future[void])">asyncFun3(): owned(Future[void])</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z2
       <li><a class="reference" href="#z2"
-    title="z2()">z2</a></li>
+    title="z2()">z2()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">bar
       <li><a class="reference" href="#bar%2CT%2CT"
-    title="bar[T](a, b: T): T">bar,<wbr>T,<wbr>T</a></li>
+    title="bar[T](a, b: T): T">bar[T](a, b: T): T</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">fromUtils3
       <li><a class="reference" href="#fromUtils3"
-    title="fromUtils3()">fromUtils3</a></li>
+    title="fromUtils3()">fromUtils3()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">isValid
       <li><a class="reference" href="#isValid%2CT"
-    title="isValid[T](x: T): bool">isValid,<wbr>T</a></li>
+    title="isValid[T](x: T): bool">isValid[T](x: T): bool</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z6
       <li><a class="reference" href="#z6"
-    title="z6(): int">z6</a></li>
+    title="z6(): int">z6(): int</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">anything
       <li><a class="reference" href="#anything"
-    title="anything()">anything</a></li>
+    title="anything()">anything()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">low
       <li><a class="reference" href="#low%2CT"
-    title="low[T: Ordinal | enum | range](x: T): T">low,<wbr>T</a></li>
+    title="low[T: Ordinal | enum | range](x: T): T">low[T: Ordinal | enum | range](x: T): T</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">p1
       <li><a class="reference" href="#p1"
-    title="p1()">p1</a></li>
+    title="p1()">p1()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z11
       <li><a class="reference" href="#z11"
-    title="z11()">z11</a></li>
+    title="z11()">z11()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">buzz
       <li><a class="reference" href="#buzz%2CT%2CT"
-    title="buzz[T](a, b: T): T">buzz,<wbr>T,<wbr>T</a></li>
+    title="buzz[T](a, b: T): T">buzz[T](a, b: T): T</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">low2
       <li><a class="reference" href="#low2%2CT"
-    title="low2[T: Ordinal | enum | range](x: T): T">low2,<wbr>T</a></li>
+    title="low2[T: Ordinal | enum | range](x: T): T">low2[T: Ordinal | enum | range](x: T): T</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z7
       <li><a class="reference" href="#z7"
-    title="z7(): int">z7</a></li>
+    title="z7(): int">z7(): int</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z13
       <li><a class="reference" href="#z13"
-    title="z13()">z13</a></li>
+    title="z13()">z13()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">baz
       <li><a class="reference" href="#baz%2CT%2CT"
-    title="baz[T](a, b: T): T">baz,<wbr>T,<wbr>T</a></li>
+    title="baz[T](a, b: T): T">baz[T](a, b: T): T</a></li>
   <li><a class="reference" href="#baz"
-    title="baz()">baz</a></li>
+    title="baz()">baz()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">addfBug14485
       <li><a class="reference" href="#addfBug14485"
-    title="addfBug14485()">addfBug14485</a></li>
+    title="addfBug14485()">addfBug14485()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">c_printf
       <li><a class="reference" href="#c_printf%2Ccstring"
-    title="c_printf(frmt: cstring): cint">c_printf,<wbr>cstring</a></li>
+    title="c_printf(frmt: cstring): cint">c_printf(frmt: cstring): cint</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z12
       <li><a class="reference" href="#z12"
-    title="z12(): int">z12</a></li>
+    title="z12(): int">z12(): int</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z3
       <li><a class="reference" href="#z3"
-    title="z3()">z3</a></li>
+    title="z3()">z3()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z9
       <li><a class="reference" href="#z9"
-    title="z9()">z9</a></li>
+    title="z9()">z9()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z4
       <li><a class="reference" href="#z4"
-    title="z4()">z4</a></li>
+    title="z4()">z4()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">someFunc
       <li><a class="reference" href="#someFunc"
-    title="someFunc()">someFunc</a></li>
+    title="someFunc()">someFunc()</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z8
       <li><a class="reference" href="#z8"
-    title="z8(): int">z8</a></li>
+    title="z8(): int">z8(): int</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z1
       <li><a class="reference" href="#z1"
-    title="z1(): Foo">z1</a></li>
+    title="z1(): Foo">z1(): Foo</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">z5
       <li><a class="reference" href="#z5"
-    title="z5(): int">z5</a></li>
+    title="z5(): int">z5(): int</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">asyncFun2
       <li><a class="reference" href="#asyncFun2"
-    title="asyncFun2(): owned(Future[void])">asyncFun2</a></li>
+    title="asyncFun2(): owned(Future[void])">asyncFun2(): owned(Future[void])</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">c_nonexistant
       <li><a class="reference" href="#c_nonexistant%2Ccstring"
-    title="c_nonexistant(frmt: cstring): cint">c_nonexistant,<wbr>cstring</a></li>
+    title="c_nonexistant(frmt: cstring): cint">c_nonexistant(frmt: cstring): cint</a></li>
 
   </ul>
   <ul class="simple nested-toc-section">asyncFun1
       <li><a class="reference" href="#asyncFun1"
-    title="asyncFun1(): Future[int]">asyncFun1</a></li>
+    title="asyncFun1(): Future[int]">asyncFun1(): Future[int]</a></li>
 
   </ul>