fix warnings/hints in nimdoc/tester.nim (#18083)

* fix warnings/hints in nimdoc/tester.nim

* improve err msg for nimdoc/tester.nim and change flag from fixup to nimTestsNimdocFixup

* address comment: put back quit instead of doAssert

nimdoc/tester.nim

@@ -1,10 +1,12 @@
 # Small program that runs the test cases for 'nim doc'.
 # 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
+# to change expected results (after carefully verifying everything), use -d:nimTestsNimdocFixup
 
 import strutils, os
 from std/private/gitutils import diffFiles
 
+const fixup = defined(nimTestsNimdocFixup)
+
 var
   failures = 0
 
@@ -62,7 +64,7 @@ let
                                      "$1/$2.nim" % [test1Dir, test1PrjName]],
                               buildIndex: @["--out:$1/$2/theindex.html" % [test1Dir, test1DocsDir],
                                             "$1/$2" % [test1Dir, test1DocsDir]])
-testNimDoc(test1Dir, test1DocsDir, test1Switches, defined(fixup))
+testNimDoc(test1Dir, test1DocsDir, test1Switches, fixup)
 
 # Test "nim doc --out:.. --index:on .."
 let
@@ -75,7 +77,7 @@ let
                                      "$1/$2.nim" % [test2Dir, test2PrjName]],
                               buildIndex: @["--out:$1/$2/theindex.html" % [test2Dir, test2DocsDir],
                                             "$1/$2" % [test2Dir, test2DocsDir]])
-testNimDoc(test2Dir, test2DocsDir, test2Switches, defined(fixup))
+testNimDoc(test2Dir, test2DocsDir, test2Switches, fixup)
 
-# Check for failures
-if failures > 0: quit($failures & " failures occurred.")
+if failures > 0:
+  quit "$# failures occurred; see note in tester.nim regarding -d:nimTestsNimdocFixup" %  $failures

nimdoc/testproject/expected/testproject.html

@@ -790,7 +790,7 @@ <h1><a class="toc-backref" href="#12">Procs</a></h1>
 <dd>
 
 
-<p><strong class="examples_text">Example:</strong></p>
+<p><strong class="examples_text">Example: cmd: --hint:XDeclaredButNotUsed:off</strong></p>
 <pre class="listing"><span class="Comment">## mullitline string litterals are tricky as their indentation can span</span>
 <span class="Comment">## below that of the runnableExamples</span>
 <span class="Keyword">let</span> <span class="Identifier">s1a</span> <span class="Operator">=</span> <span class="LongStringLit">&quot;&quot;&quot;
@@ -865,21 +865,21 @@ <h1><a class="toc-backref" href="#12">Procs</a></h1>
 <h1><a class="toc-backref" href="#14">Methods</a></h1>
 <dl class="item">
 <a id="method1.e,Moo"></a>
-<dt><pre><span class="Keyword">method</span> <a href="#method1.e%2CMoo"><span class="Identifier">method1</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <span class="Identifier">Moo</span><span class="Other">)</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dt><pre><span class="Keyword">method</span> <a href="#method1.e%2CMoo"><span class="Identifier">method1</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <span class="Identifier">Moo</span><span class="Other">)</span> {.<span class="Identifier">base</span><span class="Other">,</span> <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
 <dd>
 
 foo1
 
 </dd>
 <a id="method2.e,Moo"></a>
-<dt><pre><span class="Keyword">method</span> <a href="#method2.e%2CMoo"><span class="Identifier">method2</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <span class="Identifier">Moo</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dt><pre><span class="Keyword">method</span> <a href="#method2.e%2CMoo"><span class="Identifier">method2</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <span class="Identifier">Moo</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> {.<span class="Identifier">base</span><span class="Other">,</span> <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
 <dd>
 
 foo2
 
 </dd>
 <a id="method3.e,Moo"></a>
-<dt><pre><span class="Keyword">method</span> <a href="#method3.e%2CMoo"><span class="Identifier">method3</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <span class="Identifier">Moo</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> {.<span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
+<dt><pre><span class="Keyword">method</span> <a href="#method3.e%2CMoo"><span class="Identifier">method3</span></a><span class="Other">(</span><span class="Identifier">self</span><span class="Other">:</span> <span class="Identifier">Moo</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> {.<span class="Identifier">base</span><span class="Other">,</span> <span><span class="Other pragmadots">...</span></span><span class="pragmawrap"><span class="Identifier">raises</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Other">]</span></span>.}</pre></dt>
 <dd>
 
 foo3

nimdoc/testproject/testproject.nim

@@ -131,6 +131,7 @@ when true:
       # BUG: this currently this won't be run since not exported
       # but probably should
       doAssert false
+  if false: bazNonExported() # silence XDeclaredButNotUsed
 
   proc z17*() =
     # BUG: a comment before 1st doc comment currently doesn't prevent
@@ -212,7 +213,7 @@ when true: # tests RST inside comments
 
 when true: # multiline string litterals
   proc tripleStrLitTest*() =
-    runnableExamples:
+    runnableExamples("--hint:XDeclaredButNotUsed:off"):
       ## mullitline string litterals are tricky as their indentation can span
       ## below that of the runnableExamples
       let s1a = """
@@ -252,12 +253,12 @@ at indent 0
 
 when true: # methods; issue #14691
   type Moo = object
-  method method1*(self: Moo) =
+  method method1*(self: Moo) {.base.} =
     ## foo1
-  method method2*(self: Moo): int =
+  method method2*(self: Moo): int {.base.} =
     ## foo2
     result = 1
-  method method3*(self: Moo): int =
+  method method3*(self: Moo): int {.base.} =
     ## foo3
     1