conservative approach to fix #15184 (#16723)

compiler/lexer.nim

@@ -955,8 +955,10 @@ proc skipMultiLineComment(L: var Lexer; tok: var Token; start: int;
   # detect the amount of indentation:
   if isDoc:
     toStrip = getColNumber(L, pos)
-    while L.buf[pos] == ' ': inc pos
-    if L.buf[pos] in {CR, LF}:
+    while L.buf[pos] == ' ':
+      inc pos
+      inc toStrip
+    while L.buf[pos] in {CR, LF}:  # skip blank lines
       pos = handleCRLF(L, pos)
       toStrip = 0
       while L.buf[pos] == ' ':
@@ -1028,11 +1030,17 @@ proc scanComment(L: var Lexer, tok: var Token) =
   inc(pos, 2)
 
   var toStrip = 0
-  while L.buf[pos] == ' ':
-    inc pos
-    inc toStrip
+  var stripInit = false
 
   while true:
+    if not stripInit:  # find baseline indentation inside comment
+      while L.buf[pos] == ' ':
+        inc pos
+        inc toStrip
+      if L.buf[pos] in {CR, LF}:  # don't set toStrip in blank comment lines
+        toStrip = 0
+      else:  # found first non-whitespace character
+        stripInit = true
     var lastBackslash = -1
     while L.buf[pos] notin {CR, LF, nimlexbase.EndOfFile}:
       if L.buf[pos] == '\\': lastBackslash = pos+1
@@ -1048,11 +1056,12 @@ proc scanComment(L: var Lexer, tok: var Token) =
     if L.buf[pos] == '#' and L.buf[pos+1] == '#':
       tok.literal.add "\n"
       inc(pos, 2)
-      var c = toStrip
-      while L.buf[pos] == ' ' and c > 0:
-        inc pos
-        dec c
-      inc tok.iNumber
+      if stripInit:
+        var c = toStrip
+        while L.buf[pos] == ' ' and c > 0:
+          inc pos
+          dec c
+        inc tok.iNumber
     else:
       if L.buf[pos] > ' ':
         L.indentAhead = indent

doc/docgen.rst

@@ -76,6 +76,24 @@ Note that without the `*` following the name of the type, the documentation for
 this type would not be generated. Documentation will only be generated for
 *exported* types/procedures/etc.
 
+It's recommended to always add exactly **one** space after `##` for readability
+of comments — this extra space will be cropped from the parsed comments and
+won't influence RST formatting.
+
+.. note:: Generally, this baseline indentation level inside a documentation
+   comment may not be 1: it can be any since it is determined by the offset
+   of the first non-whitespace character in the comment.
+   After that indentation **must** be consistent on the following lines of
+   the same comment.
+   If you still need to add an additional indentation at the very beginning
+   (for RST block quote syntax) use backslash \\ before it:
+
+   .. code-block:: nim
+      ## \
+      ##
+      ##    Block quote at the first line.
+      ##
+      ## Paragraph.
 
 Nim file input
 -----------------

doc/manual.rst

@@ -247,7 +247,7 @@ Multiline documentation comments also exist and support nesting too:
 .. code-block:: nim
   proc foo =
     ##[Long documentation comment
-    here.
+       here.
     ]##
 
 

nimdoc/testproject/expected/testproject.html

@@ -190,6 +190,11 @@ window.addEventListener('DOMContentLoaded', main);
       <li><a class="reference" href="#z6"
     title="z6(): int">z6</a></li>
 
+  </ul>
+  <ul class="simple nested-toc-section">anything
+      <li><a class="reference" href="#anything"
+    title="anything()">anything</a></li>
+
   </ul>
   <ul class="simple nested-toc-section">low
       <li><a class="reference" href="#low%2CT"
@@ -794,6 +799,13 @@ ok1
 <p><strong class="examples_text">Example:</strong></p>
 <pre class="listing"><span class="Keyword">discard</span></pre>ok1
 
+</dd>
+<a id="anything"></a>
+<dt><pre><span class="Keyword">proc</span> <a href="#anything"><span class="Identifier">anything</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>
+
+There is no block quote after blank lines at the beginning.
+
 </dd>
 
 </dl></div>

nimdoc/testproject/expected/testproject.idx

@@ -59,3 +59,4 @@ Circle	testproject.html#Circle	Shapes.Circle
 Triangle	testproject.html#Triangle	Shapes.Triangle	
 Rectangle	testproject.html#Rectangle	Shapes.Rectangle	
 Shapes	testproject.html#Shapes	testproject: Shapes	
+anything	testproject.html#anything	testproject: anything()	

nimdoc/testproject/expected/theindex.html

@@ -78,6 +78,10 @@ window.addEventListener('DOMContentLoaded', 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="anything" href="#anything"><span>anything:</span></a></dt><dd><ul class="simple">
+<li><a class="reference external"
+          data-doc-search-tag="testproject: anything()" href="testproject.html#anything">testproject: anything()</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>

nimdoc/testproject/testproject.nim

@@ -375,3 +375,9 @@ when true: # issue #15702
       Circle,     ## A circle
       Triangle,   ## A three-sided shape
       Rectangle   ## A four-sided shape
+
+when true: # issue #15184
+  proc anything* =
+    ##
+    ##  There is no block quote after blank lines at the beginning.
+  discard