fix #8871 runnableExamples now preserves source code comments, litterals, and all formatting; other bug fix (#14439)

* fix #8871 runnableExamples now preserves source code comments, litterals, and all formatting
* remove orig deadcode from getAllRunnableExamplesImpl
* fix expected examples
* add test to close https://github.com/nim-lang/Nim/issues/14473
* correctly handle regular comments before 1st token inside runnableExamples
* add test to answer https://github.com/nim-lang/Nim/pull/14439#discussion_r431829199
* update tests

7 files changed, 721 insertions, 19 deletions

diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.html b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
index 469dde0ae..6e83f718f 100644
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
@@ -129,6 +129,8 @@ function main() {
     title="aEnum(): untyped"><wbr />a<wbr />Enum<span class="attachedType"></span></a></li>
   <li><a class="reference" href="#bEnum.t"
     title="bEnum(): untyped"><wbr />b<wbr />Enum<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#fromUtilsGen.t"
+    title="fromUtilsGen(): untyped"><wbr />from<wbr />Utils<wbr />Gen<span class="attachedType"></span></a></li>
 
   </ul>
 </li>
@@ -194,6 +196,15 @@ constructor.
 
 
 </dd>
+<a id="fromUtilsGen.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#fromUtilsGen.t"><span class="Identifier">fromUtilsGen</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">untyped</span></pre></dt>
+<dd>
+
+this should be shown in utils.html
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Identifier">assert</span><span class="Whitespace"> </span><span class="DecNumber">3</span><span class="Operator">*</span><span class="DecNumber">2</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">6</span></pre>ditto
+
+</dd>
 
 </dl></div>
 
diff --git a/nimdoc/testproject/expected/subdir/subdir_b/utils.idx b/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
index c848fc26a..b49a777c8 100644
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
@@ -10,3 +10,4 @@ SomeType	subdir/subdir_b/utils.html#SomeType	utils: SomeType
 someType	subdir/subdir_b/utils.html#someType_2	utils: someType(): SomeType	
 aEnum	subdir/subdir_b/utils.html#aEnum.t	utils: aEnum(): untyped	
 bEnum	subdir/subdir_b/utils.html#bEnum.t	utils: bEnum(): untyped	
+fromUtilsGen	subdir/subdir_b/utils.html#fromUtilsGen.t	utils: fromUtilsGen(): untyped	
diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index aa29c0c0d..420b60924 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -115,6 +115,9 @@ function main() {
   <li><a class="reference" href="#B"
     title="B {.inject.} = enum
   bB"><wbr />B<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#Foo"
+    title="Foo = enum
+  enumValueA2"><wbr />Foo<span class="attachedType"></span></a></li>
 
   </ul>
 </li>
@@ -149,8 +152,42 @@ function main() {
     title="baz[T](a, b: T): T"><wbr />baz<span class="attachedType"></span></a></li>
   <li><a class="reference" href="#buzz%2CT%2CT"
     title="buzz[T](a, b: T): T"><wbr />buzz<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#fromUtils3"
+    title="fromUtils3()"><wbr />from<wbr />Utils3<span class="attachedType"></span></a></li>
   <li><a class="reference" href="#isValid%2CT"
     title="isValid[T](x: T): bool"><wbr />is<wbr />Valid<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z1"
+    title="z1(): Foo"><wbr />z1<span class="attachedType">Foo</span></a></li>
+  <li><a class="reference" href="#z2"
+    title="z2()"><wbr />z2<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z3"
+    title="z3()"><wbr />z3<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z4"
+    title="z4()"><wbr />z4<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z5"
+    title="z5(): int"><wbr />z5<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z6"
+    title="z6(): int"><wbr />z6<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z7"
+    title="z7(): int"><wbr />z7<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z8"
+    title="z8(): int"><wbr />z8<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z9"
+    title="z9()"><wbr />z9<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z10"
+    title="z10()"><wbr />z10<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z11"
+    title="z11()"><wbr />z11<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z12"
+    title="z12(): int"><wbr />z12<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z13"
+    title="z13()"><wbr />z13<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#baz"
+    title="baz()"><wbr />baz<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z17"
+    title="z17()"><wbr />z17<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#p1"
+    title="p1()"><wbr />p1<span class="attachedType"></span></a></li>
 
   </ul>
 </li>
@@ -163,18 +200,42 @@ function main() {
   </ul>
 </li>
 <li>
+  <a class="reference reference-toplevel" href="#15" id="65">Iterators</a>
+  <ul class="simple simple-toc-section">
+      <li><a class="reference" href="#fromUtils1.i"
+    title="fromUtils1(): int"><wbr />from<wbr />Utils1<span class="attachedType"></span></a></li>
+
+  </ul>
+</li>
+<li>
   <a class="reference reference-toplevel" href="#17" id="67">Macros</a>
   <ul class="simple simple-toc-section">
       <li><a class="reference" href="#bar.m"
     title="bar(): untyped"><wbr />bar<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z16.m"
+    title="z16()"><wbr />z16<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z18.m"
+    title="z18(): int"><wbr />z18<span class="attachedType"></span></a></li>
 
   </ul>
 </li>
 <li>
   <a class="reference reference-toplevel" href="#18" id="68">Templates</a>
   <ul class="simple simple-toc-section">
-      <li><a class="reference" href="#foo.t%2CSomeType%2CSomeType"
+      <li><a class="reference" href="#fromUtils2.t"
+    title="fromUtils2()"><wbr />from<wbr />Utils2<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z6t.t"
+    title="z6t(): int"><wbr />z6t<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#foo.t%2CSomeType%2CSomeType"
     title="foo(a, b: SomeType)"><wbr />foo<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#myfn.t"
+    title="myfn()"><wbr />myfn<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z14.t"
+    title="z14()"><wbr />z14<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#z15.t"
+    title="z15()"><wbr />z15<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#testNimDocTrailingExample.t"
+    title="testNimDocTrailingExample()"><wbr />test<wbr />Nim<wbr />Doc<wbr />Trailing<wbr />Example<span class="attachedType"></span></a></li>
 
   </ul>
 </li>
@@ -187,13 +248,17 @@ function main() {
   
   <p class="module-desc">This is the top level module.
 <p><strong class="examples_text">Example:</strong></p>
-<pre class="listing"><span class="Keyword">import</span>
-  <span class="Identifier">subdir</span> <span class="Operator">/</span> <span class="Identifier">subdir_b</span> <span class="Operator">/</span> <span class="Identifier">utils</span>
-
-<span class="Identifier">doAssert</span> <span class="Identifier">bar</span><span class="Other">(</span><span class="DecNumber">3</span><span class="Other">,</span> <span class="DecNumber">4</span><span class="Other">)</span> <span class="Operator">==</span> <span class="DecNumber">7</span>
-<span class="Identifier">foo</span><span class="Other">(</span><span class="Identifier">enumValueA</span><span class="Other">,</span> <span class="Identifier">enumValueB</span><span class="Other">)</span>
-<span class="Keyword">for</span> <span class="Identifier">x</span> <span class="Keyword">in</span> <span class="StringLit">&quot;xx&quot;</span><span class="Other">:</span>
-  <span class="Keyword">discard</span></pre></p>
+<pre class="listing"><span class="Keyword">import</span><span class="Whitespace"> </span><span class="Identifier">subdir</span><span class="Whitespace"> </span><span class="Operator">/</span><span class="Whitespace"> </span><span class="Identifier">subdir_b</span><span class="Whitespace"> </span><span class="Operator">/</span><span class="Whitespace"> </span><span class="Identifier">utils</span><span class="Whitespace">
+</span><span class="Identifier">doAssert</span><span class="Whitespace"> </span><span class="Identifier">bar</span><span class="Punctuation">(</span><span class="DecNumber">3</span><span class="Punctuation">,</span><span class="Whitespace"> </span><span class="DecNumber">4</span><span class="Punctuation">)</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">7</span><span class="Whitespace">
+</span><span class="Identifier">foo</span><span class="Punctuation">(</span><span class="Identifier">enumValueA</span><span class="Punctuation">,</span><span class="Whitespace"> </span><span class="Identifier">enumValueB</span><span class="Punctuation">)</span><span class="Whitespace">
+</span><span class="Comment"># bug #11078</span><span class="Whitespace">
+</span><span class="Keyword">for</span><span class="Whitespace"> </span><span class="Identifier">x</span><span class="Whitespace"> </span><span class="Keyword">in</span><span class="Whitespace"> </span><span class="StringLit">&quot;xx&quot;</span><span class="Punctuation">:</span><span class="Whitespace"> </span><span class="Keyword">discard</span></pre>top2
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="StringLit">&quot;in top2&quot;</span></pre>top2 after
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="StringLit">&quot;in top3&quot;</span></pre>top3 after
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Identifier">assert</span><span class="Whitespace"> </span><span class="DecNumber">3</span><span class="Operator">*</span><span class="DecNumber">2</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">6</span></pre></p>
   <div class="section" id="6">
 <h1><a class="toc-backref" href="#6">Imports</a></h1>
 <dl class="item">
@@ -218,6 +283,14 @@ The enum A.
 The enum B.
 
 </dd>
+<a id="Foo"></a>
+<dt><pre><a href="testproject.html#Foo"><span class="Identifier">Foo</span></a> <span class="Other">=</span> <span class="Keyword">enum</span>
+  <span class="Identifier">enumValueA2</span></pre></dt>
+<dd>
+
+
+
+</dd>
 
 </dl></div>
 <div class="section" id="8">
@@ -295,6 +368,15 @@ This is deprecated without message.
 This is deprecated with a message.
 
 </dd>
+<a id="fromUtils3"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fromUtils3"><span class="Identifier">fromUtils3</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+came form utils but should be shown where <tt class="docutils literal"><span class="pre">fromUtilsGen</span></tt> is called
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">1</span></pre>
+
+</dd>
 <a id="isValid,T"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#isValid%2CT"><span class="Identifier">isValid</span></a><span class="Other">[</span><span class="Identifier">T</span><span class="Other">]</span><span class="Other">(</span><span class="Identifier">x</span><span class="Other">:</span> <span class="Identifier">T</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">bool</span></pre></dt>
 <dd>
@@ -302,6 +384,148 @@ This is deprecated with a message.
 
 
 </dd>
+<a id="z1"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z1"><span class="Identifier">z1</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <a href="testproject.html#Foo"><span class="Identifier">Foo</span></a> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz1
+
+</dd>
+<a id="z2"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z2"><span class="Identifier">z2</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz2
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="StringLit">&quot;in cz2&quot;</span></pre>
+
+</dd>
+<a id="z3"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z3"><span class="Identifier">z3</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz3
+
+</dd>
+<a id="z4"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z4"><span class="Identifier">z4</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz4
+
+</dd>
+<a id="z5"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z5"><span class="Identifier">z5</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz5
+
+</dd>
+<a id="z6"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z6"><span class="Identifier">z6</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz6
+
+</dd>
+<a id="z7"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z7"><span class="Identifier">z7</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz7
+
+</dd>
+<a id="z8"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z8"><span class="Identifier">z8</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz8
+
+</dd>
+<a id="z9"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z9"><span class="Identifier">z9</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Identifier">doAssert</span><span class="Whitespace"> </span><span class="DecNumber">1</span><span class="Whitespace"> </span><span class="Operator">+</span><span class="Whitespace"> </span><span class="DecNumber">1</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">2</span></pre>
+
+</dd>
+<a id="z10"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z10"><span class="Identifier">z10</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example: cmd: -d:foobar</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">1</span></pre>cz10
+
+</dd>
+<a id="z11"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z11"><span class="Identifier">z11</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">1</span></pre>
+
+</dd>
+<a id="z12"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z12"><span class="Identifier">z12</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">1</span></pre>
+
+</dd>
+<a id="z13"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z13"><span class="Identifier">z13</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz13
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span></pre>
+
+</dd>
+<a id="baz"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#baz"><span class="Identifier">baz</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="z17"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#z17"><span class="Identifier">z17</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cz17 rest
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">1</span></pre>rest
+
+</dd>
+<a id="p1"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#p1"><span class="Identifier">p1</span></a><span class="Other">(</span><span class="Other">)</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+cp1
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Identifier">doAssert</span><span class="Whitespace"> </span><span class="DecNumber">1</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">1</span><span class="Whitespace"> </span><span class="Comment"># regular comments work here</span></pre>c4
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Comment"># c5 regular comments before 1st token work</span><span class="Whitespace">
+</span><span class="Comment"># regular comment</span><span class="Whitespace">
+</span><span class="LongComment">#[
+nested regular comment
+]#</span><span class="Whitespace">
+</span><span class="Identifier">doAssert</span><span class="Whitespace"> </span><span class="DecNumber">2</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">2</span><span class="Whitespace"> </span><span class="Comment"># c8</span><span class="Whitespace">
+</span><span class="Comment">## this is a non-nested doc comment</span><span class="Whitespace">
+
+</span><span class="LongComment">##[
+this is a nested doc comment
+]##</span><span class="Whitespace">
+</span><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="StringLit">&quot;c9&quot;</span><span class="Whitespace">
+</span><span class="Comment"># also work after</span></pre>
+
+</dd>
 
 </dl></div>
 <div class="section" id="13">
@@ -316,6 +540,22 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 </dd>
 
 </dl></div>
+<div class="section" id="15">
+<h1><a class="toc-backref" href="#15">Iterators</a></h1>
+<dl class="item">
+<a id="fromUtils1.i"></a>
+<dt><pre><span class="Keyword">iterator</span> <a href="#fromUtils1.i"><span class="Identifier">fromUtils1</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span> <span><span class="Other">{</span><span class="Other pragmadots">...</span><span class="Other">}</span></span><span class="pragmawrap"><span class="Other">{.</span><span class="pragma"><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><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Comment"># ok1</span><span class="Whitespace">
+</span><span class="Identifier">assert</span><span class="Whitespace"> </span><span class="DecNumber">1</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">1</span><span class="Whitespace">
+</span><span class="Comment"># ok2</span></pre>
+
+</dd>
+
+</dl></div>
 <div class="section" id="17">
 <h1><a class="toc-backref" href="#17">Macros</a></h1>
 <dl class="item">
@@ -326,11 +566,43 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 
 
 </dd>
+<a id="z16.m"></a>
+<dt><pre><span class="Keyword">macro</span> <a href="#z16.m"><span class="Identifier">z16</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">1</span></pre>cz16 after
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Identifier">doAssert</span><span class="Whitespace"> </span><span class="DecNumber">2</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="DecNumber">1</span><span class="Whitespace"> </span><span class="Operator">+</span><span class="Whitespace"> </span><span class="DecNumber">1</span></pre>
+
+</dd>
+<a id="z18.m"></a>
+<dt><pre><span class="Keyword">macro</span> <a href="#z18.m"><span class="Identifier">z18</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span></pre></dt>
+<dd>
+
+cz18
+
+</dd>
 
 </dl></div>
 <div class="section" id="18">
 <h1><a class="toc-backref" href="#18">Templates</a></h1>
 <dl class="item">
+<a id="fromUtils2.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#fromUtils2.t"><span class="Identifier">fromUtils2</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
+<dd>
+
+ok3
+
+</dd>
+<a id="z6t.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#z6t.t"><span class="Identifier">z6t</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">int</span></pre></dt>
+<dd>
+
+cz6t
+
+</dd>
 <a id="foo.t,SomeType,SomeType"></a>
 <dt><pre><span class="Keyword">template</span> <a href="#foo.t%2CSomeType%2CSomeType"><span class="Identifier">foo</span></a><span class="Other">(</span><span class="Identifier">a</span><span class="Other">,</span> <span class="Identifier">b</span><span class="Other">:</span> <a href="subdir/subdir_b/utils.html#SomeType"><span class="Identifier">SomeType</span></a><span class="Other">)</span></pre></dt>
 <dd>
@@ -338,6 +610,61 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 This does nothing 
 
 </dd>
+<a id="myfn.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#myfn.t"><span class="Identifier">myfn</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">import</span><span class="Whitespace"> </span><span class="Identifier">std</span><span class="Operator">/</span><span class="Identifier">strutils</span><span class="Whitespace">
+</span><span class="Comment">## issue #8871 preserve formatting</span><span class="Whitespace">
+</span><span class="Comment">## line doc comment</span><span class="Whitespace">
+</span><span class="Comment"># bar</span><span class="Whitespace">
+</span><span class="Identifier">doAssert</span><span class="Whitespace"> </span><span class="StringLit">&quot;&apos;foo&quot;</span><span class="Whitespace"> </span><span class="Operator">==</span><span class="Whitespace"> </span><span class="StringLit">&quot;&apos;foo&quot;</span><span class="Whitespace">
+</span><span class="LongComment">##[
+foo
+bar
+]##</span><span class="Whitespace">
+
+</span><span class="Identifier">doAssert</span><span class="Punctuation">:</span><span class="Whitespace"> </span><span class="Keyword">not</span><span class="Whitespace"> </span><span class="StringLit">&quot;foo&quot;</span><span class="Operator">.</span><span class="Identifier">startsWith</span><span class="Whitespace"> </span><span class="StringLit">&quot;ba&quot;</span><span class="Whitespace">
+</span><span class="Keyword">block</span><span class="Punctuation">:</span><span class="Whitespace">
+  </span><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="HexNumber">0xff</span><span class="Whitespace"> </span><span class="Comment"># elu par cette crapule</span><span class="Whitespace">
+</span><span class="Comment"># should be in</span></pre>should be still in
+
+</dd>
+<a id="z14.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#z14.t"><span class="Identifier">z14</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
+<dd>
+
+cz14
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span></pre>
+
+</dd>
+<a id="z15.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#z15.t"><span class="Identifier">z15</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
+<dd>
+
+cz15
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span></pre>
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">3</span></pre>
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">4</span></pre>ok5 ok5b
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Identifier">assert</span><span class="Whitespace"> </span><span class="Identifier">true</span></pre>in or out?
+
+</dd>
+<a id="testNimDocTrailingExample.t"></a>
+<dt><pre><span class="Keyword">template</span> <a href="#testNimDocTrailingExample.t"><span class="Identifier">testNimDocTrailingExample</span></a><span class="Other">(</span><span class="Other">)</span></pre></dt>
+<dd>
+
+
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="DecNumber">2</span></pre>
+
+</dd>
 
 </dl></div>
 
diff --git a/nimdoc/testproject/expected/testproject.idx b/nimdoc/testproject/expected/testproject.idx
index 106c9cb76..76193de87 100644
--- a/nimdoc/testproject/expected/testproject.idx
+++ b/nimdoc/testproject/expected/testproject.idx
@@ -2,13 +2,41 @@ C_A	testproject.html#C_A	testproject: C_A
 C_B	testproject.html#C_B	testproject: C_B	
 C_C	testproject.html#C_C	testproject: C_C	
 C_D	testproject.html#C_D	testproject: C_D	
-foo	testproject.html#foo.t,SomeType,SomeType	testproject: foo(a, b: SomeType)	
 bar	testproject.html#bar,T,T	testproject: bar[T](a, b: T): T	
 baz	testproject.html#baz,T,T	testproject: baz[T](a, b: T): T	
 buzz	testproject.html#buzz,T,T	testproject: buzz[T](a, b: T): T	
-bar	testproject.html#bar.m	testproject: bar(): untyped	
 aVariable	testproject.html#aVariable	testproject: aVariable	
 A	testproject.html#A	testproject: A	
 B	testproject.html#B	testproject: B	
 someFunc	testproject.html#someFunc	testproject: someFunc()	
+fromUtils1	testproject.html#fromUtils1.i	testproject: fromUtils1(): int	
+fromUtils2	testproject.html#fromUtils2.t	testproject: fromUtils2()	
+fromUtils3	testproject.html#fromUtils3	testproject: fromUtils3()	
 isValid	testproject.html#isValid,T	testproject: isValid[T](x: T): bool	
+enumValueA2	testproject.html#enumValueA2	Foo.enumValueA2	
+Foo	testproject.html#Foo	testproject: Foo	
+z1	testproject.html#z1	testproject: z1(): Foo	
+z2	testproject.html#z2	testproject: z2()	
+z3	testproject.html#z3	testproject: z3()	
+z4	testproject.html#z4	testproject: z4()	
+z5	testproject.html#z5	testproject: z5(): int	
+z6	testproject.html#z6	testproject: z6(): int	
+z6t	testproject.html#z6t.t	testproject: z6t(): int	
+z7	testproject.html#z7	testproject: z7(): int	
+z8	testproject.html#z8	testproject: z8(): int	
+z9	testproject.html#z9	testproject: z9()	
+z10	testproject.html#z10	testproject: z10()	
+z11	testproject.html#z11	testproject: z11()	
+z12	testproject.html#z12	testproject: z12(): int	
+z13	testproject.html#z13	testproject: z13()	
+baz	testproject.html#baz	testproject: baz()	
+z17	testproject.html#z17	testproject: z17()	
+p1	testproject.html#p1	testproject: p1()	
+bar	testproject.html#bar.m	testproject: bar(): untyped	
+z16	testproject.html#z16.m	testproject: z16()	
+z18	testproject.html#z18.m	testproject: z18(): int	
+foo	testproject.html#foo.t,SomeType,SomeType	testproject: foo(a, b: SomeType)	
+myfn	testproject.html#myfn.t	testproject: myfn()	
+z14	testproject.html#z14.t	testproject: z14()	
+z15	testproject.html#z15.t	testproject: z15()	
+testNimDocTrailingExample	testproject.html#testNimDocTrailingExample.t	testproject: testNimDocTrailingExample()	
diff --git a/nimdoc/testproject/expected/theindex.html b/nimdoc/testproject/expected/theindex.html
index 18a7ca2c2..df118d8a6 100644
--- a/nimdoc/testproject/expected/theindex.html
+++ b/nimdoc/testproject/expected/theindex.html
@@ -97,6 +97,8 @@ function main() {
           </ul></dd>
 <dt><a name="baz" href="#baz"><span>baz:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
+          data-doc-search-tag="testproject: baz()" href="testproject.html#baz">testproject: baz()</a></li>
+          <li><a class="reference external"
           data-doc-search-tag="testproject: baz[T](a, b: T): T" href="testproject.html#baz%2CT%2CT">testproject: baz[T](a, b: T): T</a></li>
           </ul></dd>
 <dt><a name="bEnum" href="#bEnum"><span>bEnum:</span></a></dt><dd><ul class="simple">
@@ -127,6 +129,10 @@ function main() {
 <li><a class="reference external"
           data-doc-search-tag="SomeType.enumValueA" href="subdir/subdir_b/utils.html#enumValueA">SomeType.enumValueA</a></li>
           </ul></dd>
+<dt><a name="enumValueA2" href="#enumValueA2"><span>enumValueA2:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="Foo.enumValueA2" href="testproject.html#enumValueA2">Foo.enumValueA2</a></li>
+          </ul></dd>
 <dt><a name="enumValueB" href="#enumValueB"><span>enumValueB:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="SomeType.enumValueB" href="subdir/subdir_b/utils.html#enumValueB">SomeType.enumValueB</a></li>
@@ -135,14 +141,42 @@ function main() {
 <li><a class="reference external"
           data-doc-search-tag="SomeType.enumValueC" href="subdir/subdir_b/utils.html#enumValueC">SomeType.enumValueC</a></li>
           </ul></dd>
+<dt><a name="Foo" href="#Foo"><span>Foo:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: Foo" href="testproject.html#Foo">testproject: Foo</a></li>
+          </ul></dd>
 <dt><a name="foo" href="#foo"><span>foo:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="testproject: foo(a, b: SomeType)" href="testproject.html#foo.t%2CSomeType%2CSomeType">testproject: foo(a, b: SomeType)</a></li>
           </ul></dd>
+<dt><a name="fromUtils1" href="#fromUtils1"><span>fromUtils1:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: fromUtils1(): int" href="testproject.html#fromUtils1.i">testproject: fromUtils1(): int</a></li>
+          </ul></dd>
+<dt><a name="fromUtils2" href="#fromUtils2"><span>fromUtils2:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: fromUtils2()" href="testproject.html#fromUtils2.t">testproject: fromUtils2()</a></li>
+          </ul></dd>
+<dt><a name="fromUtils3" href="#fromUtils3"><span>fromUtils3:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: fromUtils3()" href="testproject.html#fromUtils3">testproject: fromUtils3()</a></li>
+          </ul></dd>
+<dt><a name="fromUtilsGen" href="#fromUtilsGen"><span>fromUtilsGen:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fromUtilsGen(): untyped" href="subdir/subdir_b/utils.html#fromUtilsGen.t">utils: fromUtilsGen(): untyped</a></li>
+          </ul></dd>
 <dt><a name="isValid" href="#isValid"><span>isValid:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="testproject: isValid[T](x: T): bool" href="testproject.html#isValid%2CT">testproject: isValid[T](x: T): bool</a></li>
           </ul></dd>
+<dt><a name="myfn" href="#myfn"><span>myfn:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: myfn()" href="testproject.html#myfn.t">testproject: myfn()</a></li>
+          </ul></dd>
+<dt><a name="p1" href="#p1"><span>p1:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: p1()" href="testproject.html#p1">testproject: p1()</a></li>
+          </ul></dd>
 <dt><a name="someFunc" href="#someFunc"><span>someFunc:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="testproject: someFunc()" href="testproject.html#someFunc">testproject: someFunc()</a></li>
@@ -155,6 +189,86 @@ function main() {
 <li><a class="reference external"
           data-doc-search-tag="utils: someType(): SomeType" href="subdir/subdir_b/utils.html#someType_2">utils: someType(): SomeType</a></li>
           </ul></dd>
+<dt><a name="testNimDocTrailingExample" href="#testNimDocTrailingExample"><span>testNimDocTrailingExample:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: testNimDocTrailingExample()" href="testproject.html#testNimDocTrailingExample.t">testproject: testNimDocTrailingExample()</a></li>
+          </ul></dd>
+<dt><a name="z1" href="#z1"><span>z1:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z1(): Foo" href="testproject.html#z1">testproject: z1(): Foo</a></li>
+          </ul></dd>
+<dt><a name="z10" href="#z10"><span>z10:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z10()" href="testproject.html#z10">testproject: z10()</a></li>
+          </ul></dd>
+<dt><a name="z11" href="#z11"><span>z11:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z11()" href="testproject.html#z11">testproject: z11()</a></li>
+          </ul></dd>
+<dt><a name="z12" href="#z12"><span>z12:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z12(): int" href="testproject.html#z12">testproject: z12(): int</a></li>
+          </ul></dd>
+<dt><a name="z13" href="#z13"><span>z13:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z13()" href="testproject.html#z13">testproject: z13()</a></li>
+          </ul></dd>
+<dt><a name="z14" href="#z14"><span>z14:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z14()" href="testproject.html#z14.t">testproject: z14()</a></li>
+          </ul></dd>
+<dt><a name="z15" href="#z15"><span>z15:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z15()" href="testproject.html#z15.t">testproject: z15()</a></li>
+          </ul></dd>
+<dt><a name="z16" href="#z16"><span>z16:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z16()" href="testproject.html#z16.m">testproject: z16()</a></li>
+          </ul></dd>
+<dt><a name="z17" href="#z17"><span>z17:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z17()" href="testproject.html#z17">testproject: z17()</a></li>
+          </ul></dd>
+<dt><a name="z18" href="#z18"><span>z18:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z18(): int" href="testproject.html#z18.m">testproject: z18(): int</a></li>
+          </ul></dd>
+<dt><a name="z2" href="#z2"><span>z2:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z2()" href="testproject.html#z2">testproject: z2()</a></li>
+          </ul></dd>
+<dt><a name="z3" href="#z3"><span>z3:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z3()" href="testproject.html#z3">testproject: z3()</a></li>
+          </ul></dd>
+<dt><a name="z4" href="#z4"><span>z4:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z4()" href="testproject.html#z4">testproject: z4()</a></li>
+          </ul></dd>
+<dt><a name="z5" href="#z5"><span>z5:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z5(): int" href="testproject.html#z5">testproject: z5(): int</a></li>
+          </ul></dd>
+<dt><a name="z6" href="#z6"><span>z6:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z6(): int" href="testproject.html#z6">testproject: z6(): int</a></li>
+          </ul></dd>
+<dt><a name="z6t" href="#z6t"><span>z6t:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z6t(): int" href="testproject.html#z6t.t">testproject: z6t(): int</a></li>
+          </ul></dd>
+<dt><a name="z7" href="#z7"><span>z7:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z7(): int" href="testproject.html#z7">testproject: z7(): int</a></li>
+          </ul></dd>
+<dt><a name="z8" href="#z8"><span>z8:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z8(): int" href="testproject.html#z8">testproject: z8(): int</a></li>
+          </ul></dd>
+<dt><a name="z9" href="#z9"><span>z9:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: z9()" href="testproject.html#z9">testproject: z9()</a></li>
+          </ul></dd>
 </dl>
     <div class="row">
       <div class="twelve-columns footer">
diff --git a/nimdoc/testproject/subdir/subdir_b/utils.nim b/nimdoc/testproject/subdir/subdir_b/utils.nim
index 0576f194f..ad8f3d162 100644
--- a/nimdoc/testproject/subdir/subdir_b/utils.nim
+++ b/nimdoc/testproject/subdir/subdir_b/utils.nim
@@ -21,6 +21,8 @@ More text.
 
 ]##
 
+# BUG: module link in theindex.html is wrong, see #14434
+
 type
   SomeType* = enum
     enumValueA,
@@ -48,3 +50,23 @@ template bEnum*(): untyped =
     ## Stuff in `quotes` here.
     ## [Some link](https://nim-lang.org)
     discard
+
+template fromUtilsGen*(): untyped =
+  ## this should be shown in utils.html
+  runnableExamples:
+    assert 3*2 == 6
+  ## ditto
+
+  iterator fromUtils1*(): int =
+    runnableExamples:
+      # ok1
+      assert 1 == 1
+      # ok2
+    yield 15
+
+  template fromUtils2*() =
+    ## ok3
+
+  proc fromUtils3*() =
+    ## came form utils but should be shown where `fromUtilsGen` is called
+    runnableExamples: discard 1
diff --git a/nimdoc/testproject/testproject.nim b/nimdoc/testproject/testproject.nim
index d1fcf58cd..39bbe3dc5 100644
--- a/nimdoc/testproject/testproject.nim
+++ b/nimdoc/testproject/testproject.nim
@@ -9,17 +9,22 @@ runnableExamples:
   # bug #11078
   for x in "xx": discard
 
+when true:
+  ## top2
+  runnableExamples:
+    discard "in top2"
+  ## top2 after
+
+runnableExamples:
+  discard "in top3"
+## top3 after
+
 const
   C_A* = 0x7FF0000000000000'f64
   C_B* = 0o377'i8
   C_C* = 0o277'i8
   C_D* = 0o177777'i16
 
-template foo*(a, b: SomeType) =
-  ## This does nothing
-  ##
-  discard
-
 proc bar*[T](a, b: T): T =
   result = a + b
 
@@ -33,13 +38,207 @@ proc buzz*[T](a, b: T): T {.deprecated: "since v0.20".} =
 
 import std/macros
 
-macro bar*(): untyped =
-  result = newStmtList()
-
 var aVariable*: array[1, int]
 
+# bug #9432
 aEnum()
 bEnum()
+fromUtilsGen()
 
-# bug #9432
 proc isValid*[T](x: T): bool = x.len > 0
+
+when true:
+  # these cases appear redundant but they're actually (almost) all different at
+  # AST level and needed to ensure docgen keeps working, eg because of issues
+  # like D20200526T163511
+  type
+    Foo* = enum
+      enumValueA2
+
+  proc z1*(): Foo =
+    ## cz1
+    Foo.default
+
+  proc z2*() =
+    ## cz2
+    runnableExamples:
+      discard "in cz2"
+
+  proc z3*() =
+    ## cz3
+
+  proc z4*() =
+    ## cz4
+    discard
+
+when true:
+  # tests for D20200526T163511
+  proc z5*(): int =
+    ## cz5
+    return 1
+
+  proc z6*(): int =
+    ## cz6
+    1
+
+  template z6t*(): int =
+    ## cz6t
+    1
+
+  proc z7*(): int =
+    ## cz7
+    result = 1
+
+  proc z8*(): int =
+    ## cz8
+    block:
+      discard
+      1+1
+
+when true:
+  # interleaving 0 or more runnableExamples and doc comments, issue #9227
+  proc z9*() =
+    runnableExamples: doAssert 1 + 1 == 2
+
+  proc z10*() =
+    runnableExamples "-d:foobar":
+      discard 1
+    ## cz10
+
+  proc z11*() =
+    runnableExamples:
+      discard 1
+    discard
+
+  proc z12*(): int =
+    runnableExamples:
+      discard 1
+    12
+
+  proc z13*() =
+    ## cz13
+    runnableExamples:
+      discard
+
+  proc baz*() = discard
+
+  proc bazNonExported() =
+    ## out (not exported)
+    runnableExamples:
+      # BUG: this currently this won't be run since not exported
+      # but probably should
+      doAssert false
+
+  proc z17*() =
+    # BUG: a comment before 1st doc comment currently doesn't prevent
+    # doc comment from being docgen'd; probably should be fixed
+    ## cz17
+    ## rest
+    runnableExamples:
+      discard 1
+    ## rest
+    # this comment separates docgen'd doc comments
+    ## out
+
+when true: # capture non-doc comments correctly even before 1st token
+  proc p1*() =
+    ## cp1
+    runnableExamples: doAssert 1 == 1 # regular comments work here
+    ## c4
+    runnableExamples:
+      # c5 regular comments before 1st token work
+      # regular comment
+      #[
+      nested regular comment
+      ]#
+      doAssert 2 == 2 # c8
+      ## this is a non-nested doc comment
+
+      ##[
+      this is a nested doc comment
+      ]##
+      discard "c9"
+      # also work after
+    # this should be out
+
+when true: # (most) macros
+  macro bar*(): untyped =
+    result = newStmtList()
+
+  macro z16*() =
+    runnableExamples: discard 1
+    ## cz16
+    ## after
+    runnableExamples:
+      doAssert 2 == 1 + 1
+    # BUG: we should probably render `cz16\nafter` by keeping newline instead or
+    # what it currently renders as: `cz16 after`
+
+  macro z18*(): int =
+    ## cz18
+    newLit 0
+
+when true: # (most) templates
+  template foo*(a, b: SomeType) =
+    ## This does nothing
+    ##
+    discard
+
+  template myfn*() =
+    runnableExamples:
+      import std/strutils
+      ## issue #8871 preserve formatting
+      ## line doc comment
+      # bar
+      doAssert "'foo" == "'foo"
+      ##[
+      foo
+      bar
+      ]##
+
+      doAssert: not "foo".startsWith "ba"
+      block:
+        discard 0xff # elu par cette crapule
+      # should be in
+    ## should be still in
+
+    # out
+    ## out
+
+  template z14*() =
+    ## cz14
+    runnableExamples:
+      discard
+
+  template z15*() =
+    ## cz15
+    runnableExamples:
+      discard
+    runnableExamples: discard 3
+    runnableExamples: discard 4
+    ## ok5
+    ## ok5b
+    runnableExamples: assert true
+
+    ## in or out?
+    # this is an edge case; a newline separate last runnableExamples from 
+    # next doc comment but AST isnt' aware of it; this could change in future
+    discard 8
+    ## out
+    runnableExamples: discard 1
+
+when true: # issue #14473
+  import std/[sequtils]
+  template doit(): untyped =
+    ## doit
+    ## return output only
+    toSeq([1,2])
+  echo doit() # using doAssert or similar to avoid echo would "hide" the original bug
+
+when true:
+  template testNimDocTrailingExample*() =
+    # this must be last entry in this file, it checks against a bug (that got fixed)
+    # where runnableExamples would not show if there was not at least 2 "\n" after
+    # the last character of runnableExamples
+    runnableExamples:
+      discard 2
\ No newline at end of file