tools: make v doc -f md module output useful by default (#24737)

cmd/tools/vdoc/markdown.v

@@ -28,16 +28,16 @@ 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 != '' {
 			hw.writeln(' '.repeat(2 * indent) + '- [${slug(cn.name)}](#${cn.name})')
 			cw.writeln('## ${cn.name}')
 		}
 		if cn.content.len > 0 {
-			if cn.comments.len > 0 && cfg.include_comments {
+			cw.writeln('```v\n${cn.content}\n```\n')
+			if cn.comments.len > 0 {
 				comments := cn.merge_comments_without_examples()
-				cw.writeln('```v\n${cn.content}\n```\n${comments}\n')
+				cw.writeln('${comments}\n')
 			}
 			// Write examples if any found
 			examples := cn.examples()

cmd/tools/vdoc/testdata/output_formats/main.md

@@ -0,0 +1,168 @@
+# module main
+
+
+## Contents
+- [Constants](#Constants)
+- [abc](#abc)
+- [def](#def)
+- [xyz](#xyz)
+- [MyXMLDocument.abc](#MyXMLDocument.abc)
+- [MyXMLDocument.from_file](#MyXMLDocument.from_file)
+- [MyXMLDocument.from_text](#MyXMLDocument.from_text)
+- [MyXMLDocument](#MyXMLDocument)
+  - [instance_from_file](#instance_from_file)
+  - [instance_from_text](#instance_from_text)
+  - [instance_abc](#instance_abc)
+  - [instance_void](#instance_void)
+  - [instance_int](#instance_int)
+  - [instance_result](#instance_result)
+  - [instance_option](#instance_option)
+
+## Constants
+```v
+const omega = 3 // should be first
+```
+
+[[Return to contents]](#Contents)
+
+```v
+const alpha = 5 // should be in the middle
+```
+
+[[Return to contents]](#Contents)
+
+```v
+const beta = 2 // should be at the end
+```
+
+[[Return to contents]](#Contents)
+
+## abc
+```v
+fn abc()
+```
+
+abc - should be last
+
+[[Return to contents]](#Contents)
+
+## def
+```v
+fn def()
+```
+
+def - should be first
+
+[[Return to contents]](#Contents)
+
+## xyz
+```v
+fn xyz()
+```
+
+xyz - should be in the middle a small script <script>console.log('hello');</script> bold text <b>bold</b> end underlined text <u>underline</u> end a link [main v repo](https://github.com/vlang/v)
+
+[[Return to contents]](#Contents)
+
+## MyXMLDocument.abc
+```v
+fn MyXMLDocument.abc(text string) ?(string, int)
+```
+
+MyXMLDocument.abc does something too... I just do not know what.
+
+[[Return to contents]](#Contents)
+
+## MyXMLDocument.from_file
+```v
+fn MyXMLDocument.from_file(path string) !MyXMLDocument
+```
+
+MyXMLDocument.from_text processes the file path, and returns an error
+
+[[Return to contents]](#Contents)
+
+## MyXMLDocument.from_text
+```v
+fn MyXMLDocument.from_text(text string) ?MyXMLDocument
+```
+
+MyXMLDocument.from_text processes text and produces none
+
+[[Return to contents]](#Contents)
+
+## MyXMLDocument
+```v
+struct MyXMLDocument {
+	path string
+}
+```
+
+MyXMLDocument is here just to test the different combinations of methods/output types
+
+[[Return to contents]](#Contents)
+
+## instance_from_file
+```v
+fn (x &MyXMLDocument) instance_from_file(path string) !MyXMLDocument
+```
+
+instance_from_file does stuff with path
+
+[[Return to contents]](#Contents)
+
+## instance_from_text
+```v
+fn (x &MyXMLDocument) instance_from_text(text string) ?MyXMLDocument
+```
+
+instance_from_text does stuff with text
+
+[[Return to contents]](#Contents)
+
+## instance_abc
+```v
+fn (x &MyXMLDocument) instance_abc(text string) ?(string, int)
+```
+
+instance_abc does stuff too
+
+[[Return to contents]](#Contents)
+
+## instance_void
+```v
+fn (x &MyXMLDocument) instance_void()
+```
+
+instance_void does stuff too
+
+[[Return to contents]](#Contents)
+
+## instance_int
+```v
+fn (x &MyXMLDocument) instance_int() int
+```
+
+instance_int does stuff too
+
+[[Return to contents]](#Contents)
+
+## instance_result
+```v
+fn (x &MyXMLDocument) instance_result() !
+```
+
+instance_error does stuff too
+
+[[Return to contents]](#Contents)
+
+## instance_option
+```v
+fn (x &MyXMLDocument) instance_option() ?
+```
+
+instance_option does stuff too
+
+[[Return to contents]](#Contents)
+
+#### Powered by vdoc.

cmd/tools/vdoc/vdoc_file_test.v

@@ -30,9 +30,10 @@ fn test_output() {
 		// test the main 3 different formats:
 		program_dir := os.quoted_path(if os.is_dir(path) { path } else { os.dir(path) })
 		for fmt in ['html', 'ansi', 'text'] {
-			fails += check_output('${vexe} doc -f ${fmt} -o - -html-only-contents -readme -comments ${program_dir}',
+			fails += check_output('${vexe} doc -no-timestamp -f ${fmt} -o - -html-only-contents -readme -comments ${program_dir}',
 				'${path_no_ext}.${fmt}')
 		}
+		fails += check_output('${vexe} doc -no-timestamp -f md -o - ${program_dir}', '${path_no_ext}.md')
 		if fails == 0 {
 			println(term.green('OK'))
 		} else {