fix #14691 docgen works again for methods (#14701)

* fix #14691 docgen methods

* fixup

5 files changed, 110 insertions, 14 deletions

diff --git a/compiler/docgen.nim b/compiler/docgen.nim
index 0af830a42..a973bdfc1 100644
--- a/compiler/docgen.nim
+++ b/compiler/docgen.nim
@@ -609,21 +609,12 @@ proc getRoutineBody(n: PNode): PNode =
 
   so we normalize the results to get to the statement list containing the
   (0 or more) doc comments and runnableExamples.
-  (even if using `result = n[bodyPos]`, you'd still to apply similar logic).
   ]##
-  result = n[^1]
-  case result.kind
-  of nkSym:
-    result = n[^2]
-    case result.kind
-      of nkAsgn:
-        doAssert result[0].kind == nkSym
-        doAssert result.len == 2
-        result = result[1]
-      else: # eg: nkStmtList
-        discard
-  else:
-    discard
+  result = n[bodyPos]
+  if result.kind == nkAsgn and n.len > bodyPos+1 and n[bodyPos+1].kind == nkSym:
+    doAssert result[0].kind == nkSym
+    doAssert result.len == 2
+    result = result[1]
 
 proc getAllRunnableExamples(d: PDoc, n: PNode, dest: var Rope) =
   var n = n
diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index 7bd2e64a3..a4f8876fd 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -212,10 +212,26 @@ function main() {
   </ul>
 </li>
 <li>
+  <a class="reference reference-toplevel" href="#14" id="64">Methods</a>
+  <ul class="simple simple-toc-section">
+      <li><a class="reference" href="#method1.e%2CMoo"
+    title="method1(self: Moo)"><wbr />method1<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#method2.e%2CMoo"
+    title="method2(self: Moo): int"><wbr />method2<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#method3.e%2CMoo"
+    title="method3(self: Moo): int"><wbr />method3<span class="attachedType"></span></a></li>
+
+  </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>
+  <li><a class="reference" href="#iter1.i%2Cint"
+    title="iter1(n: int): int"><wbr />iter1<span class="attachedType"></span></a></li>
+  <li><a class="reference" href="#iter2.i%2Cint"
+    title="iter2(n: int): int"><wbr />iter2<span class="attachedType"></span></a></li>
 
   </ul>
 </li>
@@ -654,6 +670,32 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 </dd>
 
 </dl></div>
+<div class="section" id="14">
+<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">{</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>
+
+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">{</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>
+
+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">{</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>
+
+foo3
+
+</dd>
+
+</dl></div>
 <div class="section" id="15">
 <h1><a class="toc-backref" href="#15">Iterators</a></h1>
 <dl class="item">
@@ -668,6 +710,22 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 </span><span class="Comment"># ok2</span></pre>
 
 </dd>
+<a id="iter1.i,int"></a>
+<dt><pre><span class="Keyword">iterator</span> <a href="#iter1.i%2Cint"><span class="Identifier">iter1</span></a><span class="Other">(</span><span class="Identifier">n</span><span class="Other">:</span> <span class="Identifier">int</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>
+
+foo1
+
+</dd>
+<a id="iter2.i,int"></a>
+<dt><pre><span class="Keyword">iterator</span> <a href="#iter2.i%2Cint"><span class="Identifier">iter2</span></a><span class="Other">(</span><span class="Identifier">n</span><span class="Other">:</span> <span class="Identifier">int</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>
+
+foo2
+<p><strong class="examples_text">Example:</strong></p>
+<pre class="listing"><span class="Keyword">discard</span><span class="Whitespace"> </span><span class="Comment"># bar</span></pre>
+
+</dd>
 
 </dl></div>
 <div class="section" id="17">
diff --git a/nimdoc/testproject/expected/testproject.idx b/nimdoc/testproject/expected/testproject.idx
index 46798f314..6d0bc6c5e 100644
--- a/nimdoc/testproject/expected/testproject.idx
+++ b/nimdoc/testproject/expected/testproject.idx
@@ -38,6 +38,11 @@ c_nonexistant	testproject.html#c_nonexistant,cstring	testproject: c_nonexistant(
 low	testproject.html#low,T	testproject: low[T: Ordinal | enum | range](x: T): T	
 low2	testproject.html#low2,T	testproject: low2[T: Ordinal | enum | range](x: T): T	
 tripleStrLitTest	testproject.html#tripleStrLitTest	testproject: tripleStrLitTest()	
+method1	testproject.html#method1.e,Moo	testproject: method1(self: Moo)	
+method2	testproject.html#method2.e,Moo	testproject: method2(self: Moo): int	
+method3	testproject.html#method3.e,Moo	testproject: method3(self: Moo): int	
+iter1	testproject.html#iter1.i,int	testproject: iter1(n: int): int	
+iter2	testproject.html#iter2.i,int	testproject: iter2(n: int): int	
 bar	testproject.html#bar.m	testproject: bar(): untyped	
 z16	testproject.html#z16.m	testproject: z16()	
 z18	testproject.html#z18.m	testproject: z18(): int	
diff --git a/nimdoc/testproject/expected/theindex.html b/nimdoc/testproject/expected/theindex.html
index 14d07bfd9..8d34506a6 100644
--- a/nimdoc/testproject/expected/theindex.html
+++ b/nimdoc/testproject/expected/theindex.html
@@ -181,6 +181,14 @@ function main() {
 <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="iter1" href="#iter1"><span>iter1:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: iter1(n: int): int" href="testproject.html#iter1.i%2Cint">testproject: iter1(n: int): int</a></li>
+          </ul></dd>
+<dt><a name="iter2" href="#iter2"><span>iter2:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: iter2(n: int): int" href="testproject.html#iter2.i%2Cint">testproject: iter2(n: int): int</a></li>
+          </ul></dd>
 <dt><a name="low" href="#low"><span>low:</span></a></dt><dd><ul class="simple">
 <li><a class="reference external"
           data-doc-search-tag="testproject: low[T: Ordinal | enum | range](x: T): T" href="testproject.html#low%2CT">testproject: low[T: Ordinal | enum | range](x: T): T</a></li>
@@ -189,6 +197,18 @@ function main() {
 <li><a class="reference external"
           data-doc-search-tag="testproject: low2[T: Ordinal | enum | range](x: T): T" href="testproject.html#low2%2CT">testproject: low2[T: Ordinal | enum | range](x: T): T</a></li>
           </ul></dd>
+<dt><a name="method1" href="#method1"><span>method1:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: method1(self: Moo)" href="testproject.html#method1.e%2CMoo">testproject: method1(self: Moo)</a></li>
+          </ul></dd>
+<dt><a name="method2" href="#method2"><span>method2:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: method2(self: Moo): int" href="testproject.html#method2.e%2CMoo">testproject: method2(self: Moo): int</a></li>
+          </ul></dd>
+<dt><a name="method3" href="#method3"><span>method3:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: method3(self: Moo): int" href="testproject.html#method3.e%2CMoo">testproject: method3(self: Moo): int</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>
diff --git a/nimdoc/testproject/testproject.nim b/nimdoc/testproject/testproject.nim
index b05754d51..5282c6f77 100644
--- a/nimdoc/testproject/testproject.nim
+++ b/nimdoc/testproject/testproject.nim
@@ -247,6 +247,28 @@ at indent 0
       # should be in
     # should be out
 
+when true: # methods; issue #14691
+  type Moo = object
+  method method1*(self: Moo) =
+    ## foo1
+  method method2*(self: Moo): int =
+    ## foo2
+    result = 1
+  method method3*(self: Moo): int =
+    ## foo3
+    1
+
+when true: # iterators
+  iterator iter1*(n: int): int =
+    ## foo1
+    for i in 0..<n:
+      yield i
+  iterator iter2*(n: int): int =
+    ## foo2
+    runnableExamples:
+      discard # bar
+    yield 0
+
 when true: # (most) macros
   macro bar*(): untyped =
     result = newStmtList()