vdoc: fix vlang#8044 and -comments flag (vlang#20592)

cmd/tools/vdoc/markdown.v

@@ -4,17 +4,19 @@ import strings
 import v.doc
 
 fn (vd VDoc) gen_markdown(d doc.Doc, with_toc bool) string {
+	cfg := vd.cfg
 	mut hw := strings.new_builder(200)
 	mut cw := strings.new_builder(200)
-	hw.writeln('# ${d.head.content}\n')
-	if d.head.comments.len > 0 {
+	hw.writeln('# ${d.head.content}')
+	if d.head.comments.len > 0 && cfg.include_comments {
 		comments := if vd.cfg.include_examples {
 			d.head.merge_comments()
 		} else {
 			d.head.merge_comments_without_examples()
 		}
-		hw.writeln('${comments}\n')
+		hw.writeln('${comments}')
 	}
+	hw.writeln('\n')
 	if with_toc {
 		hw.writeln('## Contents')
 	}
@@ -25,14 +27,17 @@ fn (vd VDoc) gen_markdown(d doc.Doc, with_toc bool) string {
 }
 
 fn (vd VDoc) write_markdown_content(contents []doc.DocNode, mut cw strings.Builder, mut hw strings.Builder, indent int, with_toc bool) {
+	cfg := vd.cfg
 	for cn in contents {
 		if with_toc && cn.name.len > 0 {
 			hw.writeln(' '.repeat(2 * indent) + '- [${slug(cn.name)}](#${cn.name})')
 			cw.writeln('## ${cn.name}')
 		}
 		if cn.content.len > 0 {
-			comments := cn.merge_comments_without_examples()
-			cw.writeln('```v\n${cn.content}\n```\n${comments}\n')
+			if cn.comments.len > 0 && cfg.include_comments {
+				comments := cn.merge_comments_without_examples()
+				cw.writeln('```v\n${cn.content}\n```\n${comments}\n')
+			}
 			// Write examples if any found
 			examples := cn.examples()
 			if vd.cfg.include_examples && examples.len > 0 {

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

@@ -0,0 +1,5 @@
+module rec
+    v doc -f html -o doc rec.v (doc should be an empty folder) I would like to see these 2 lines in HTML-generated header documentation
+
+fn fib(n int) int
+    fib Calculates the recursive fibonacci series `n` is the rank to pass to function I See these 3 lines only

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

@@ -0,0 +1,3 @@
+module rec
+
+fn fib(n int) int

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

@@ -0,0 +1,10 @@
+// v doc -f html -o doc rec.v (doc should be an empty folder)
+// I would like to see these 2 lines in HTML-generated header documentation
+module rec
+
+// fib Calculates the recursive fibonacci series
+// `n` is the rank to pass to function
+// I See these 3 lines only
+pub fn fib(n int) int {
+	return if n < 2 { n } else { fib(n - 1) + fib(n - 2) }
+}

cmd/tools/vdoc/vdoc.v

@@ -51,12 +51,16 @@ struct ParallelDoc {
 fn (vd &VDoc) gen_json(d doc.Doc) string {
 	cfg := vd.cfg
 	mut jw := strings.new_builder(200)
-	comments := if cfg.include_examples {
-		d.head.merge_comments()
-	} else {
-		d.head.merge_comments_without_examples()
+	jw.write_string('{"module_name":"${d.head.name}",')
+	if d.head.comments.len > 0 && cfg.include_comments {
+		comments := if cfg.include_examples {
+			d.head.merge_comments()
+		} else {
+			d.head.merge_comments_without_examples()
+		}
+		jw.write_string('"description":"${escape(comments)}",')
 	}
-	jw.write_string('{"module_name":"${d.head.name}","description":"${escape(comments)}","contents":')
+	jw.write_string('"contents":')
 	jw.write_string(json.encode(d.contents.keys().map(d.contents[it])))
 	jw.write_string(',"generator":"vdoc","time_generated":"${d.time_generated.str()}"}')
 	return jw.str()
@@ -67,9 +71,9 @@ fn (mut vd VDoc) gen_plaintext(d doc.Doc) string {
 	mut pw := strings.new_builder(200)
 	if cfg.is_color {
 		content_arr := d.head.content.split(' ')
-		pw.writeln('${term.bright_blue(content_arr[0])} ${term.green(content_arr[1])}\n')
+		pw.writeln('${term.bright_blue(content_arr[0])} ${term.green(content_arr[1])}')
 	} else {
-		pw.writeln('${d.head.content}\n')
+		pw.writeln('${d.head.content}')
 	}
 	if cfg.include_comments {
 		comments := if cfg.include_examples {
@@ -81,6 +85,7 @@ fn (mut vd VDoc) gen_plaintext(d doc.Doc) string {
 			pw.writeln(indent(comments))
 		}
 	}
+	pw.writeln('')
 	vd.write_plaintext_content(d.contents.arr(), mut pw)
 	return pw.str()
 }

vlib/v/doc/doc.v

@@ -348,13 +348,13 @@ pub fn (mut d Doc) file_ast(mut file_ast ast.File) map[string]DocNode {
 			}
 			// the previous comments were probably a copyright/license one
 			module_comment := merge_doc_comments(preceding_comments)
-			preceding_comments = []
 			if !d.is_vlib && !module_comment.starts_with('Copyright (c)') {
 				if module_comment == '' {
 					continue
 				}
 				d.head.comments << preceding_comments
 			}
+			preceding_comments = []
 			continue
 		}
 		if last_import_stmt_idx > 0 && sidx == last_import_stmt_idx {
@@ -437,7 +437,7 @@ pub fn (mut d Doc) generate() ! {
 	} else {
 		os.real_path(os.dir(d.base_path))
 	}
-	d.is_vlib = !d.base_path.contains('vlib')
+	d.is_vlib = d.base_path.contains('vlib')
 	project_files := os.ls(d.base_path) or { return err }
 	v_files := d.prefs.should_compile_filtered_files(d.base_path, project_files)
 	if v_files.len == 0 {
@@ -514,7 +514,7 @@ pub fn (mut d Doc) file_asts(mut file_asts []ast.File) ! {
 }
 
 // generate documents a certain file directory and returns an
-// instance of `Doc` if it is successful. Otherwise, it will  throw an error.
+// instance of `Doc` if it is successful. Otherwise, it will throw an error.
 pub fn generate(input_path string, pub_only bool, with_comments bool, platform Platform, filter_symbol_names ...string) !Doc {
 	if platform == .js {
 		return error('vdoc: Platform `${platform}` is not supported.')