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

* fix #14691 docgen methods * fixup
2025-12-28 17:04:41 +00:00 · 2020-06-17 23:47:16 -07:00
parent 7df27b5035
commit bb62feff72
5 changed files with 110 additions and 14 deletions
--- 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
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -211,11 +211,27 @@ 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>
@@ -653,6 +669,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>
@@ -667,6 +709,22 @@ My someFunc. Stuff in <tt class="docutils literal"><span class="pre">quotes</spa
 </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>
+<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>
--- 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	
--- 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>
--- 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()