diff --git a/compiler/lexer.nim b/compiler/lexer.nim
index b55dd35859..729ba34352 100644
--- a/compiler/lexer.nim
+++ b/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
diff --git a/doc/docgen.rst b/doc/docgen.rst
index bbf0838bb5..09f6504c81 100644
--- a/doc/docgen.rst
+++ b/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
-----------------
diff --git a/doc/manual.rst b/doc/manual.rst
index 9fabee1e8d..4ef962f3ad 100644
--- a/doc/manual.rst
+++ b/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.
]##
diff --git a/nimdoc/testproject/expected/testproject.html b/nimdoc/testproject/expected/testproject.html
index 2bf8855c73..c60d9f26a9 100644
--- a/nimdoc/testproject/expected/testproject.html
+++ b/nimdoc/testproject/expected/testproject.html
@@ -190,6 +190,11 @@ window.addEventListener('DOMContentLoaded', main);