From 91d50e415c2ebc57b98807d65b5244459f1687f1 Mon Sep 17 00:00:00 2001 From: Pierre Curto Date: Sat, 27 Jan 2024 06:10:50 +0100 Subject: [PATCH] vdoc: fix #8044 and -comments flag (#20592) --- cmd/tools/vdoc/markdown.v | 15 ++++++++++----- .../tests/testdata/comments/main.comments.out | 5 +++++ .../vdoc/tests/testdata/comments/main.out | 3 +++ cmd/tools/vdoc/tests/testdata/comments/main.v | 10 ++++++++++ cmd/tools/vdoc/vdoc.v | 19 ++++++++++++------- vlib/v/doc/doc.v | 6 +++--- 6 files changed, 43 insertions(+), 15 deletions(-) create mode 100644 cmd/tools/vdoc/tests/testdata/comments/main.comments.out create mode 100644 cmd/tools/vdoc/tests/testdata/comments/main.out create mode 100644 cmd/tools/vdoc/tests/testdata/comments/main.v diff --git a/cmd/tools/vdoc/markdown.v b/cmd/tools/vdoc/markdown.v index c74331a21c8f6f..5f0e40ed087a7c 100644 --- a/cmd/tools/vdoc/markdown.v +++ b/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 { diff --git a/cmd/tools/vdoc/tests/testdata/comments/main.comments.out b/cmd/tools/vdoc/tests/testdata/comments/main.comments.out new file mode 100644 index 00000000000000..0efdadf7caf5d8 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/cmd/tools/vdoc/tests/testdata/comments/main.out b/cmd/tools/vdoc/tests/testdata/comments/main.out new file mode 100644 index 00000000000000..c6b36eea130ba8 --- /dev/null +++ b/cmd/tools/vdoc/tests/testdata/comments/main.out @@ -0,0 +1,3 @@ +module rec + +fn fib(n int) int \ No newline at end of file diff --git a/cmd/tools/vdoc/tests/testdata/comments/main.v b/cmd/tools/vdoc/tests/testdata/comments/main.v new file mode 100644 index 00000000000000..1d44d028c6b1c9 --- /dev/null +++ b/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) } +} diff --git a/cmd/tools/vdoc/vdoc.v b/cmd/tools/vdoc/vdoc.v index 3950867a7c3f87..279b274c9e6363 100644 --- a/cmd/tools/vdoc/vdoc.v +++ b/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() } diff --git a/vlib/v/doc/doc.v b/vlib/v/doc/doc.v index 8bab33decbd22c..e76873f9cb0bb6 100644 --- a/vlib/v/doc/doc.v +++ b/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.')