vdoc: improve creation of trimmed node descriptions, extend tests (#21281)

Author: ttytm

.github/workflows/module_docs_ci.yml

@@ -13,6 +13,12 @@ jobs:
       - uses: actions/checkout@v4
       - name: Build V
         run: make
+      - name: Test v doc
+        run: |
+          # While the integration tests (executing the v doc command) should install
+          # markdown automatically, unit tests won't. Run integration tests first.
+          ./v test cmd/tools/vdoc/tests/
+          ./v test cmd/tools/vdoc/*.v
       - name: Build module documentation
         run: ./v doc -m -f html vlib/
       - name: Deploy docs to vercel

cmd/tools/vdoc/html.v

@@ -132,7 +132,7 @@ fn (mut vd VDoc) collect_search_index(out Output) {
 			doc.head.merge_comments_without_examples()
 		}
 		vd.search_module_data << SearchModuleResult{
-			description: trim_doc_node_description(comments)
+			description: trim_doc_node_description(mod, comments)
 			link: vd.get_file_name(mod, out)
 		}
 		for _, dn in doc.contents {
@@ -151,7 +151,7 @@ fn (mut vd VDoc) create_search_results(mod string, dn doc.DocNode, out Output) {
 	} else {
 		dn.merge_comments_without_examples()
 	}
-	dn_description := trim_doc_node_description(comments)
+	dn_description := trim_doc_node_description(dn.name, comments)
 	vd.search_index << dn.name
 	vd.search_data << SearchResult{
 		prefix: if dn.parent_name != '' { '${dn.kind} (${dn.parent_name})' } else { '${dn.kind} ' }

cmd/tools/vdoc/utils.v

@@ -33,13 +33,25 @@ fn is_module_readme(dn doc.DocNode) bool {
 	return dn.comments.len > 0 && (dn.content == 'module ${dn.name}' || dn.name == 'README')
 }
 
-fn trim_doc_node_description(desc string) string {
+// trim_doc_node_description returns the nodes trimmed description.
+// An example use are the descriptions of the search results in the sidebar.
+fn trim_doc_node_description(mod_name string, desc string) string {
 	mut dn_desc := desc.replace_each(['\r\n', '\n', '"', '\\"'])
-	// Handle module READMEs.
-	if dn_desc.starts_with('## Description\n\n') {
-		dn_desc = dn_desc['## Description\n\n'.len..].all_before('\n')
-		if dn_desc.starts_with('`') && dn_desc.count('`') > 1 {
-			dn_desc = dn_desc.all_after('`').all_after('`').trim_left(' ')
+	// Get the first "descriptive" line.
+	if dn_desc.starts_with('#') {
+		// Handle module READMEs.
+		for l in dn_desc.split_into_lines()[1..] {
+			if l != '' && !l.starts_with('#') {
+				quoted_mod_name := '`${mod_name}`'
+				if l.starts_with(quoted_mod_name) {
+					// Omit the module name in the description as it is redundant since the name is displayed as well.
+					// "`arrays` is a module that..." -> "is a module that..."
+					dn_desc = l.all_after(quoted_mod_name).trim_left(' ')
+				} else {
+					dn_desc = l
+				}
+				break
+			}
 		}
 	} else {
 		dn_desc = dn_desc.all_before('\n')
@@ -48,7 +60,7 @@ fn trim_doc_node_description(desc string) string {
 	if dn_desc.len > 80 {
 		dn_desc = dn_desc[..80]
 	}
-	// If `\` is last character, it ends with `\"` which leads to a JS error.
+	// If `\` is the last character, it ends with `\"` which leads to a JS error.
 	return dn_desc.trim_string_right('\\')
 }
 

cmd/tools/vdoc/utils_test.v

@@ -0,0 +1,18 @@
+module main
+
+fn test_trim_doc_node_description() {
+	mod := 'foo'
+	mut readme := '## Description
+
+`foo` is a module that provides tools and utility functions to assist in working with bar.
+It also assists with composing and testing baz.'
+	expected := 'is a module that provides tools and utility functions to assist in working with'
+	res := trim_doc_node_description(mod, readme).trim_space()
+	assert res == expected
+
+	readme = '# Foo
+`foo` is a module that provides tools and utility functions to assist in working with bar.
+It also assists with composing and testing baz.'
+	res2 := trim_doc_node_description(mod, readme).trim_space()
+	assert res2 == res
+}

cmd/tools/vtest-self.v

@@ -84,6 +84,7 @@ const essential_list = [
 ]
 const skip_test_files = [
 	'do_not_remove',
+	'cmd/tools/vdoc/utils_test.v', // markdown not installed
 	'vlib/context/deadline_test.v', // sometimes blocks
 	'vlib/context/onecontext/onecontext_test.v', // backtrace_symbols is missing
 	'vlib/db/mysql/mysql_orm_test.v', // mysql not installed