doc: update linebreak logic, handle "highlight-comments" (#19967)

cmd/tools/vdoc/tests/testdata/multiline/main.comments.out

@@ -5,5 +5,40 @@ fn a1()
 fn a2()
     this should be merged into the same line
 fn a3()
-    This should be its own parapgraph, because it ends with a dot.  
+    This should be its own parapgraph.
+
     This should be another paragraph.
+fn a4()
+    This should be merged into one parapgraph.
+
+    Note: this should be it's own paragraph.
+fn a5()
+    This should be its own parapgraph.
+
+    Note: this should also be it own paragraph
+
+    Note: this should be it's own paragraph.
+fn a6()
+    A comment
+
+    Fixme: this should be it's own paragraph.
+
+    Fixme: this should be it's own paragraph.
+
+    Fixme: this should be it's own paragraph.
+fn a7()
+    A comment
+
+    Todo: this should be it's own paragraph.
+
+    Todo: this should be it's own paragraph.
+
+    Todo: this should be it's own paragraph.
+fn a8()
+    A comment
+
+    Todo: this should be it's own paragraph.
+
+    Note: this should be it's own paragraph.
+
+    Fixme: this should be it's own paragraph.

cmd/tools/vdoc/tests/testdata/multiline/main.out

@@ -3,3 +3,8 @@ module main
 fn a1()
 fn a2()
 fn a3()
+fn a4()
+fn a5()
+fn a6()
+fn a7()
+fn a8()

cmd/tools/vdoc/tests/testdata/multiline/main.v

@@ -9,8 +9,47 @@ pub fn a2() {
 	println('hi')
 }
 
-// This should be its own parapgraph, because it ends with a dot.
+// This should be its own parapgraph.
+//
 // This should be another paragraph.
 pub fn a3() {
 	println('hi')
 }
+
+// This should be merged
+// into one parapgraph.
+// Note: this should be it's own paragraph.
+pub fn a4() {
+	println('hi')
+}
+
+// This should be its own parapgraph.
+// NOTE: this should also be it own paragraph
+// note: this should be it's own paragraph.
+pub fn a5() {
+	println('hi')
+}
+
+// A comment
+// Fixme: this should be it's own paragraph.
+// fixme: this should be it's own paragraph.
+// FIXME: this should be it's own paragraph.
+pub fn a6() {
+	println('hi')
+}
+
+// A comment
+// TODO: this should be it's own paragraph.
+// todo: this should be it's own paragraph.
+// Todo: this should be it's own paragraph.
+pub fn a7() {
+	println('hi')
+}
+
+// A comment
+// TODO: this should be it's own paragraph.
+// NOTE: this should be it's own paragraph.
+// FIXME: this should be it's own paragraph.
+pub fn a8() {
+	println('hi')
+}

cmd/tools/vdoc/tests/testdata/newlines/main.comments.out

@@ -3,8 +3,7 @@ module main
 fn funky()
     hello
 
-    empty line
-    newline using a full stop.  
+    line after empty line, newline after commentline.
     ```v
     code
     ```

cmd/tools/vdoc/tests/testdata/newlines/main.v

@@ -1,7 +1,7 @@
 // hello
 //
-// empty line
-// newline using a full stop.
+// line after empty line,
+// newline after commentline.
 // ```v
 // code
 // ```

cmd/tools/vdoc/theme/doc.css

@@ -408,6 +408,8 @@ hr {
 	font-size: 1rem;
 	line-height: 1.6;
 	letter-spacing: 0.025em;
+	max-width: 100ch;
+	word-wrap: break-word;
 }
 .doc-content a {
 	color: #2779bd;

vlib/v/doc/utils.v

@@ -69,19 +69,31 @@ pub fn merge_doc_comments(comments []DocComment) string {
 	}
 	commentlines = commentlines.reverse()
 	mut is_codeblock := false
-	mut previously_newline := true
+	mut next_on_newline := true
 	mut comment := ''
 	for line in commentlines {
 		if line.starts_with('```') {
 			is_codeblock = !is_codeblock
-			comment = comment + '\n' + line
+			comment += '\n' + line
 			continue
 		} else if is_codeblock {
-			comment = comment + '\n' + line
+			comment += '\n' + line
 			continue
 		}
 
-		line_trimmed := line.trim(' ')
+		line_trimmed := line.trim(' ').to_lower()
+
+		// Use own paragraph for "highlight" comments.
+		if line_trimmed.starts_with('note:') {
+			comment += '\n\nNote:${line['note:'.len..]}'
+			continue
+		} else if line_trimmed.starts_with('fixme:') {
+			comment += '\n\nFixme:${line['fixme:'.len..]}'
+			continue
+		} else if line_trimmed.starts_with('todo:') {
+			comment += '\n\nTodo:${line['todo:'.len..]}'
+			continue
+		}
 
 		mut is_horizontalrule := false
 		line_no_spaces := line_trimmed.replace(' ', '')
@@ -97,15 +109,12 @@ pub fn merge_doc_comments(comments []DocComment) string {
 			|| (line.starts_with('#') && line.before(' ').count('#') == line.before(' ').len)
 			|| (line_trimmed.starts_with('|') && line_trimmed.ends_with('|'))
 			|| line_trimmed.starts_with('- ') {
-			comment = comment + '\n' + line
-			previously_newline = true
-		} else if line.ends_with('.') {
-			comment = comment + '\n' + line + '  '
-			previously_newline = true
+			comment += '\n' + line
+			next_on_newline = true
 		} else {
-			sep := if previously_newline { '\n' } else { ' ' }
-			comment = comment + sep + line
-			previously_newline = false
+			sep := if next_on_newline { '\n' } else { ' ' }
+			comment += sep + line
+			next_on_newline = false
 		}
 	}
 	return comment