support same-line doc comments in routines (#18595)

* support same-line comments in routines * remove assert as per review comment
2026-01-06 13:07:48 +00:00 · 2021-07-27 10:50:59 -07:00
parent 4920b06973
commit 8d2f6bba3a
6 changed files with 205 additions and 1 deletions
--- a/compiler/parser.nim
+++ b/compiler/parser.nim
@@ -1795,6 +1795,13 @@ proc parseRoutine(p: var Parser, kind: TNodeKind): PNode =
  else:
    result.add(p.emptyNode)
  indAndComment(p, result, maybeMissEquals)
+  let body = result[^1]
+  if body.kind == nkStmtList and body.len > 0 and body[0].comment.len > 0 and body[0].kind != nkCommentStmt:
+    if result.comment.len == 0:
+      # proc fn*(a: int): int = a ## foo
+      # => moves comment `foo` to `fn`
+      swap(result.comment, body[0].comment)
+    else: discard # xxx either `assert false` or issue a warning (otherwise we'll never know of this edge case)

 proc newCommentStmt(p: var Parser): PNode =
  #| commentStmt = COMMENT
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.html
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.html
@@ -115,7 +115,52 @@ window.addEventListener('DOMContentLoaded', main);
 <li>
  <a class="reference reference-toplevel" href="#12" id="62">Procs</a>
  <ul class="simple simple-toc-section">
-      <ul class="simple nested-toc-section">someType
+      <ul class="simple nested-toc-section">fn2
+      <li><a class="reference" href="#fn2"
+    title="fn2()">fn2()</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn3
+      <li><a class="reference" href="#fn3"
+    title="fn3(): auto">fn3(): auto</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn4
+      <li><a class="reference" href="#fn4"
+    title="fn4(): auto">fn4(): auto</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn5
+      <li><a class="reference" href="#fn5"
+    title="fn5()">fn5()</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn6
+      <li><a class="reference" href="#fn6"
+    title="fn6()">fn6()</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn7
+      <li><a class="reference" href="#fn7"
+    title="fn7()">fn7()</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn8
+      <li><a class="reference" href="#fn8"
+    title="fn8(): auto">fn8(): auto</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn9
+      <li><a class="reference" href="#fn9%2Cint"
+    title="fn9(a: int): int">fn9(a: int): int</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">fn10
+      <li><a class="reference" href="#fn10%2Cint"
+    title="fn10(a: int): int">fn10(a: int): int</a></li>
+
+  </ul>
+  <ul class="simple nested-toc-section">someType
      <li><a class="reference" href="#someType_2"
    title="someType(): SomeType">someType(): SomeType</a></li>

@@ -181,6 +226,69 @@ window.addEventListener('DOMContentLoaded', main);
 <div class="section" id="12">
 <h1><a class="toc-backref" href="#12">Procs</a></h1>
 <dl class="item">
+<a id="fn2"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fn2"><span class="Identifier">fn2</span></a><span class="Other">(</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>
+
+comment
+
+</dd>
+<a id="fn3"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fn3"><span class="Identifier">fn3</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">auto</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>
+
+comment
+
+</dd>
+<a id="fn4"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fn4"><span class="Identifier">fn4</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">auto</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>
+
+comment
+
+</dd>
+<a id="fn5"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fn5"><span class="Identifier">fn5</span></a><span class="Other">(</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>
+
+comment
+
+</dd>
+<a id="fn6"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fn6"><span class="Identifier">fn6</span></a><span class="Other">(</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>
+
+comment
+
+</dd>
+<a id="fn7"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fn7"><span class="Identifier">fn7</span></a><span class="Other">(</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>
+
+comment
+
+</dd>
+<a id="fn8"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#fn8"><span class="Identifier">fn8</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <span class="Identifier">auto</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>
+
+comment
+
+</dd>
+<a id="fn9,int"></a>
+<dt><pre><span class="Keyword">func</span> <a href="#fn9%2Cint"><span class="Identifier">fn9</span></a><span class="Other">(</span><span class="Identifier">a</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 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>
+
+comment
+
+</dd>
+<a id="fn10,int"></a>
+<dt><pre><span class="Keyword">func</span> <a href="#fn10%2Cint"><span class="Identifier">fn10</span></a><span class="Other">(</span><span class="Identifier">a</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 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>
+
+comment
+
+</dd>
 <a id="someType_2"></a>
 <dt><pre><span class="Keyword">proc</span> <a href="#someType_2"><span class="Identifier">someType</span></a><span class="Other">(</span><span class="Other">)</span><span class="Other">:</span> <a href="utils.html#SomeType"><span class="Identifier">SomeType</span></a> {.<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>
--- a/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
+++ b/nimdoc/testproject/expected/subdir/subdir_b/utils.idx
@@ -3,6 +3,15 @@ enumValueB	subdir/subdir_b/utils.html#enumValueB	SomeType.enumValueB
 enumValueC	subdir/subdir_b/utils.html#enumValueC	SomeType.enumValueC	
 SomeType	subdir/subdir_b/utils.html#SomeType	utils: SomeType	
 someType	subdir/subdir_b/utils.html#someType_2	utils: someType(): SomeType	
+fn2	subdir/subdir_b/utils.html#fn2	utils: fn2()	
+fn3	subdir/subdir_b/utils.html#fn3	utils: fn3(): auto	
+fn4	subdir/subdir_b/utils.html#fn4	utils: fn4(): auto	
+fn5	subdir/subdir_b/utils.html#fn5	utils: fn5()	
+fn6	subdir/subdir_b/utils.html#fn6	utils: fn6()	
+fn7	subdir/subdir_b/utils.html#fn7	utils: fn7()	
+fn8	subdir/subdir_b/utils.html#fn8	utils: fn8(): auto	
+fn9	subdir/subdir_b/utils.html#fn9,int	utils: fn9(a: int): int	
+fn10	subdir/subdir_b/utils.html#fn10,int	utils: fn10(a: int): int	
 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	
--- a/nimdoc/testproject/expected/theindex.html
+++ b/nimdoc/testproject/expected/theindex.html
@@ -171,6 +171,42 @@ window.addEventListener('DOMContentLoaded', 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="fn10" href="#fn10"><span>fn10:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn10(a: int): int" href="subdir/subdir_b/utils.html#fn10%2Cint">utils: fn10(a: int): int</a></li>
+          </ul></dd>
+<dt><a name="fn2" href="#fn2"><span>fn2:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn2()" href="subdir/subdir_b/utils.html#fn2">utils: fn2()</a></li>
+          </ul></dd>
+<dt><a name="fn3" href="#fn3"><span>fn3:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn3(): auto" href="subdir/subdir_b/utils.html#fn3">utils: fn3(): auto</a></li>
+          </ul></dd>
+<dt><a name="fn4" href="#fn4"><span>fn4:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn4(): auto" href="subdir/subdir_b/utils.html#fn4">utils: fn4(): auto</a></li>
+          </ul></dd>
+<dt><a name="fn5" href="#fn5"><span>fn5:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn5()" href="subdir/subdir_b/utils.html#fn5">utils: fn5()</a></li>
+          </ul></dd>
+<dt><a name="fn6" href="#fn6"><span>fn6:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn6()" href="subdir/subdir_b/utils.html#fn6">utils: fn6()</a></li>
+          </ul></dd>
+<dt><a name="fn7" href="#fn7"><span>fn7:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn7()" href="subdir/subdir_b/utils.html#fn7">utils: fn7()</a></li>
+          </ul></dd>
+<dt><a name="fn8" href="#fn8"><span>fn8:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn8(): auto" href="subdir/subdir_b/utils.html#fn8">utils: fn8(): auto</a></li>
+          </ul></dd>
+<dt><a name="fn9" href="#fn9"><span>fn9:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="utils: fn9(a: int): int" href="subdir/subdir_b/utils.html#fn9%2Cint">utils: fn9(a: int): int</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>
--- a/nimdoc/testproject/subdir/subdir_b/utils.nim
+++ b/nimdoc/testproject/subdir/subdir_b/utils.nim
@@ -31,6 +31,23 @@ proc someType*(): SomeType =
  ## constructor.
  SomeType(2)

+
+proc fn2*() = discard ## comment
+proc fn3*(): auto = 1 ## comment
+proc fn4*(): auto = 2 * 3 + 4 ## comment
+proc fn5*() ## comment
+proc fn5*() = discard
+proc fn6*() =
+  ## comment
+proc fn7*() =
+  ## comment
+  discard
+proc fn8*(): auto =
+  ## comment
+  1+1
+func fn9*(a: int): int = 42  ## comment
+func fn10*(a: int): int = a  ## comment
+
 # bug #9235

 template aEnum*(): untyped =
--- a/tests/stdlib/trepr.nim
+++ b/tests/stdlib/trepr.nim
@@ -9,6 +9,7 @@ from strutils import endsWith, contains, strip
 from std/macros import newLit

 macro deb(a): string = newLit a.repr.strip
+macro debTyped(a: typed): string = newLit a.repr.strip

 template main() =
  doAssert repr({3,5}) == "{3, 5}"
@@ -243,5 +244,31 @@ template bar(): untyped =
    echo "baz"
    4)"""

+  block: # one liner doc comments
+    let a1 = deb:
+      func fn1(): int = 1  ## comment
+      func fn2(): int = 1
+        ## comment
+    let a2 = debTyped:
+      func fn1(): int = 1  ## comment
+      func fn2(): int = 1
+        ## comment
+    doAssert a1 == """
+func fn1(): int =
+  ## comment
+  1
+
+func fn2(): int =
+  ## comment
+  1"""
+    doAssert a2 == """
+func fn1(): int =
+  ## comment
+  result = 1
+
+func fn2(): int =
+  ## comment
+  result = 1"""
+
 static: main()
 main()