fix #14846; add macros.extractDocCommentsAndRunnables (#14849)

* fix #14846; add macros.extractDocCommentsAndRunnables

* fixup

* update tests

* address comment

4 files changed, 58 insertions, 0 deletions

diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index a4f8876fd..648ecb629 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -200,6 +200,12 @@ function main() {
     title="low2[T: Ordinal | enum | range](x: T): T"><wbr />low2<span class="attachedType"></span></a></li>
   <li><a class="reference" href="#tripleStrLitTest"
     title="tripleStrLitTest()"><wbr />triple<wbr />Str<wbr />Lit<wbr />Test<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#asyncFun1"
+    title="asyncFun1(): Future[int]"><wbr />async<wbr />Fun1<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#asyncFun2"
+    title="asyncFun2(): owned(Future[void])"><wbr />async<wbr />Fun2<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#asyncFun3"
+    title="asyncFun3(): owned(Future[void])"><wbr />async<wbr />Fun3<span class="attachedType"></span></a></li>
 
   </ul>
 </li>
@@ -656,6 +662,29 @@ at indent 0
 </span><span class="Comment"># should be in</span></pre>
 
 </dd>
+<a id="asyncFun1"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun1"><span class="Identifier">asyncFun1</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">int</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="Identifier">Exception</span><span class="Other">,</span> <span class="Identifier">ValueError</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+ok1
+
+</dd>
+<a id="asyncFun2"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun2"><span class="Identifier">asyncFun2</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">owned</span><span class="Other">(</span><span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">void</span><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="Identifier">Exception</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</span><span class="Other">]</span></span><span class="Other">.}</span></span></pre></dt>
+<dd>
+
+
+
+</dd>
+<a id="asyncFun3"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#asyncFun3"><span class="Identifier">asyncFun3</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">owned</span><span class="Other">(</span><span class="Identifier">Future</span><span class="Other">[</span><span class="Identifier">void</span><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="Identifier">Exception</span><span class="Other">]</span><span class="Other">,</span> <span class="Identifier">tags</span><span class="Other">:</span> <span class="Other">[</span><span class="Identifier">RootEffect</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></pre>ok1
+
+</dd>
 
 </dl></div>
 <div class="section" id="13">
diff --git a/nimdoc/testproject/expected/testproject.idx b/nimdoc/testproject/expected/testproject.idx
index 6d0bc6c5e..0b75b29d2 100644
--- a/nimdoc/testproject/expected/testproject.idx
+++ b/nimdoc/testproject/expected/testproject.idx
@@ -50,4 +50,7 @@ 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()	
+asyncFun1	testproject.html#asyncFun1	testproject: asyncFun1(): Future[int]	
+asyncFun2	testproject.html#asyncFun2	testproject: asyncFun2(): owned(Future[void])	
+asyncFun3	testproject.html#asyncFun3	testproject: asyncFun3(): owned(Future[void])	
 testNimDocTrailingExample	testproject.html#testNimDocTrailingExample.t	testproject: testNimDocTrailingExample()	
diff --git a/nimdoc/testproject/expected/theindex.html b/nimdoc/testproject/expected/theindex.html
index 8d34506a6..0b835c409 100644
--- a/nimdoc/testproject/expected/theindex.html
+++ b/nimdoc/testproject/expected/theindex.html
@@ -85,6 +85,18 @@ function main() {
 <li><a class="reference external"
           data-doc-search-tag="utils: aEnum(): untyped" href="subdir/subdir_b/utils.html#aEnum.t">utils: aEnum(): untyped</a></li>
           </ul></dd>
+<dt><a name="asyncFun1" href="#asyncFun1"><span>asyncFun1:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: asyncFun1(): Future[int]" href="testproject.html#asyncFun1">testproject: asyncFun1(): Future[int]</a></li>
+          </ul></dd>
+<dt><a name="asyncFun2" href="#asyncFun2"><span>asyncFun2:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: asyncFun2(): owned(Future[void])" href="testproject.html#asyncFun2">testproject: asyncFun2(): owned(Future[void])</a></li>
+          </ul></dd>
+<dt><a name="asyncFun3" href="#asyncFun3"><span>asyncFun3:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: asyncFun3(): owned(Future[void])" href="testproject.html#asyncFun3">testproject: asyncFun3(): owned(Future[void])</a></li>
+          </ul></dd>
 <dt><a name="aVariable" href="#aVariable"><span>aVariable:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="testproject: aVariable" href="testproject.html#aVariable">testproject: aVariable</a></li>
diff --git a/nimdoc/testproject/testproject.nim b/nimdoc/testproject/testproject.nim
index 5282c6f77..25cdf39a4 100644
--- a/nimdoc/testproject/testproject.nim
+++ b/nimdoc/testproject/testproject.nim
@@ -343,6 +343,20 @@ when true: # issue #14473
     toSeq([1,2])
   echo doit() # using doAssert or similar to avoid echo would "hide" the original bug
 
+when true: # issue #14846
+  import asyncdispatch
+  proc asyncFun1*(): Future[int] {.async.} =
+    ## ok1
+    result = 1
+  proc asyncFun2*() {.async.} = discard
+  proc asyncFun3*() {.async.} =
+    runnableExamples:
+      discard
+    ## ok1
+    discard
+    ## should be out
+    discard
+
 when true:
   template testNimDocTrailingExample*() =
     # this must be last entry in this file, it checks against a bug (that got fixed)