From 5a4dbf19d0c449696f579591b3ea6a3f0b1c06ae Mon Sep 17 00:00:00 2001 From: Delyan Angelov Date: Thu, 31 Jul 2025 10:33:35 +0300 Subject: [PATCH] tools: fix `return""` in vdoc html output (fix #24979) --- cmd/tools/vdoc/html.v | 6 ++- .../vdoc/testdata/output_formats/README.md | 26 +++++++++++ .../vdoc/testdata/output_formats/main.ansi | 45 +++++++++++++++++++ .../vdoc/testdata/output_formats/main.html | 11 ++++- .../vdoc/testdata/output_formats/main.text | 26 +++++++++++ .../testdata/readme_in_project_root/README.md | 17 +++++++ .../src/main.readme.comments.out | 12 +++++ vlib/regex/README.md | 2 +- 8 files changed, 142 insertions(+), 3 deletions(-) diff --git a/cmd/tools/vdoc/html.v b/cmd/tools/vdoc/html.v index 5e9cb9b9f7..49683789be 100644 --- a/cmd/tools/vdoc/html.v +++ b/cmd/tools/vdoc/html.v @@ -384,6 +384,7 @@ fn write_token(tok token.Token, typ HighlightTokenTyp, mut buf strings.Builder) fn html_highlight(code string, tb &ast.Table) string { mut s := scanner.new_scanner(code, .parse_comments, &pref.Preferences{ output_mode: .silent }) mut tok := s.scan() + mut prev_tok := tok mut next_tok := s.scan() mut buf := strings.new_builder(200) mut i := 0 @@ -490,6 +491,9 @@ fn html_highlight(code string, tb &ast.Table) string { // html documentation outputs / its style rules will affect the readme. buf.write_string("'${html.escape(tok.lit.str())}'") } else { + if final_tok_typ == .string && prev_tok.lit == 'return' { + buf.write_string(' ') + } write_token(tok, tok_typ, mut buf) } buf.write_string('') @@ -506,7 +510,7 @@ fn html_highlight(code string, tb &ast.Table) string { if i - 1 == next_tok.pos { i-- } - + prev_tok = tok tok = next_tok next_tok = s.scan() } diff --git a/cmd/tools/vdoc/testdata/output_formats/README.md b/cmd/tools/vdoc/testdata/output_formats/README.md index 3c8bbdc3bc..cdebaa4912 100644 --- a/cmd/tools/vdoc/testdata/output_formats/README.md +++ b/cmd/tools/vdoc/testdata/output_formats/README.md @@ -11,6 +11,32 @@ This is a script `` . ## Examples +### Functions that return different literals: + +Example of a function returning boolean: +```v +fn is_odd(x int) bool { + if x % 2 == 0 { + return false + } + return true +} +``` + +Another example of a function returning a string: +```v +fn answer() string { + return '42' +} +``` + +This example shows a function returning a string with interpolation: +```v +fn str_with_interplation() string { + return 'this string has ${42:6} interpolation in it.' +} +``` + ### Processing command line args ```v diff --git a/cmd/tools/vdoc/testdata/output_formats/main.ansi b/cmd/tools/vdoc/testdata/output_formats/main.ansi index 965869d46e..d1afa9ea56 100644 --- a/cmd/tools/vdoc/testdata/output_formats/main.ansi +++ b/cmd/tools/vdoc/testdata/output_formats/main.ansi @@ -5,6 +5,25 @@ This is a link to the main V site. This is a bold text. This is a script . Examples +Functions that return different literals: +Example of a function returning boolean: +fn is_odd(x int) bool { + if x % 2 == 0 { + return false + } + return true +} + +Another example of a function returning a string: +fn answer() string { + return '42' +} + +This example shows a function returning a string with interpolation: +fn str_with_interplation() string { + return 'this string has ${42:6} interpolation in it.' +} + Processing command line args import os @@ -150,6 +169,32 @@ The End. ## Examples + ### Functions that return different literals: + + Example of a function returning boolean: + ```v + fn is_odd(x int) bool { + if x % 2 == 0 { + return false + } + return true + } + ``` + + Another example of a function returning a string: + ```v + fn answer() string { + return '42' + } + ``` + + This example shows a function returning a string with interpolation: + ```v + fn str_with_interplation() string { + return 'this string has ${42:6} interpolation in it.' + } + ``` + ### Processing command line args ```v diff --git a/cmd/tools/vdoc/testdata/output_formats/main.html b/cmd/tools/vdoc/testdata/output_formats/main.html index fe74760622..1cc37c15c1 100644 --- a/cmd/tools/vdoc/testdata/output_formats/main.html +++ b/cmd/tools/vdoc/testdata/output_formats/main.html @@ -1,6 +1,15 @@

main #

-

Description

This is an example of a an .md file, used for adding more rich text documentation in a project or module.

This is a link to the main V site.

This is a bold text.

This is a script <script>console.log('hi from README.md');</script> .

Examples

Processing command line args

import os
+
Description
This is an example of a an .md file, used for adding more rich text documentation in a project or module.
This is a link to the main V site.
This is a bold text.
This is a script <script>console.log('hi from README.md');</script> .
Examples
Functions that return different literals:
Example of a function returning boolean:
fn is_odd(x int) bool {
+    if x % 2 == 0 {
+        return false
+    }
+    return true
+}
Another example of a function returning a string:
fn answer() string {
+    return '42'
+}
This example shows a function returning a string with interpolation:
fn str_with_interplation() string {
+    return 'this string has ${42:6} interpolation in it.'
+}
Processing command line args
import os
 
 fn main() {
     dump(os.args)
diff --git a/cmd/tools/vdoc/testdata/output_formats/main.text b/cmd/tools/vdoc/testdata/output_formats/main.text
index 21579c4da7..9332bcffe9 100644
--- a/cmd/tools/vdoc/testdata/output_formats/main.text
+++ b/cmd/tools/vdoc/testdata/output_formats/main.text
@@ -11,6 +11,32 @@ module main
     
     ## Examples
     
+    ### Functions that return different literals:
+    
+    Example of a function returning boolean:
+    ```v
+    fn is_odd(x int) bool {
+    	if x % 2 == 0 {
+    		return false
+    	}
+    	return true
+    }
+    ```
+    
+    Another example of a function returning a string:
+    ```v
+    fn answer() string {
+    	return '42'
+    }
+    ```
+    
+    This example shows a function returning a string with interpolation:
+    ```v
+    fn str_with_interplation() string {
+    	return 'this string has ${42:6} interpolation in it.'
+    }
+    ```
+    
     ### Processing command line args
     
     ```v
diff --git a/cmd/tools/vdoc/testdata/readme_in_project_root/README.md b/cmd/tools/vdoc/testdata/readme_in_project_root/README.md
index 0bc2274399..7a2a2c6ab1 100644
--- a/cmd/tools/vdoc/testdata/readme_in_project_root/README.md
+++ b/cmd/tools/vdoc/testdata/readme_in_project_root/README.md
@@ -1 +1,18 @@
 hello from readme
+
+Example:
+```v
+fn is_odd(x int) bool {
+	if x % 2 == 0 {
+		return false
+	}
+	return true
+}
+```
+
+Another example:
+```v
+fn answer() string {
+	return '42'
+}
+```
diff --git a/cmd/tools/vdoc/testdata/readme_in_project_root/src/main.readme.comments.out b/cmd/tools/vdoc/testdata/readme_in_project_root/src/main.readme.comments.out
index e426e3ec2f..f6e2f15335 100644
--- a/cmd/tools/vdoc/testdata/readme_in_project_root/src/main.readme.comments.out
+++ b/cmd/tools/vdoc/testdata/readme_in_project_root/src/main.readme.comments.out
@@ -1,4 +1,16 @@
 hello from readme
+Example:
+fn is_odd(x int) bool {
+    if x % 2 == 0 {
+        return false
+    }
+    return true
+}
+
+Another example:
+fn answer() string {
+    return '42'
+}
 module foo
 
 fn bar()
diff --git a/vlib/regex/README.md b/vlib/regex/README.md
index a9ce7b94b3..0c43671817 100644
--- a/vlib/regex/README.md
+++ b/vlib/regex/README.md
@@ -531,7 +531,7 @@ pub fn new() RE
 After an initializer is used, the regex expression must be compiled with:
 
 ```v ignore
-// compile_opt compile RE pattern string,  returning an error if the compilation fails
+// compile_opt compile RE pattern string, returning an error if the compilation fails
 pub fn (mut re RE) compile_opt(pattern string) !
 ```