TheCloud/v
1
0
Fork 0
mirror of https://github.com/vlang/v.git synced 2025-09-12 00:46:55 -04:00
Code Issues Packages Projects Releases Wiki Activity

vdoc: update merge_doc_comments so recent fixes extend to all output formats (#21289)

Browse Source
This commit is contained in:
Turiiya 2024-04-15 17:16:27 +02:00 committed by GitHub
parent 107c43a34d
commit 0b83ea77c9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
4 changed files with 131 additions and 151 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
cmd/tools/vdoc/html.v
View File

@ -506,43 +506,12 @@ fn html_highlight(code string, tb &ast.Table) string {
fn doc_node_html(dn doc.DocNode, link string, head bool, include_examples bool, tb &ast.Table) string { fn doc_node_html(dn doc.DocNode, link string, head bool, include_examples bool, tb &ast.Table) string {
mut dnw := strings.new_builder(200) mut dnw := strings.new_builder(200)
head_tag := if head { 'h1' } else { 'h2' } head_tag := if head { 'h1' } else { 'h2' }
// Allow README.md to go through unescaped except for script tags
escaped_html := if head && is_module_readme(dn) {
readme_lines := dn.comments[0].text.split_into_lines()
mut merged_lines := []string{}
mut is_codeblock := false
for i := 0; i < readme_lines.len; i++ {
l := readme_lines[i]
nl := readme_lines[i + 1] or {
merged_lines << l
break
}
l_trimmed := l.trim_left('\x01').trim_space()
if l_trimmed.starts_with('```') {
is_codeblock = !is_codeblock
}
// -> if l_trimmed.len > 1 && (is_ul || is_ol)
is_list := l_trimmed.len > 1 && ((l_trimmed[1] == ` ` && l_trimmed[0] in [`*`, `-`])
|| (l_trimmed.len > 2 && l_trimmed[2] == ` ` && l_trimmed[1] == `.`
&& l_trimmed[0].is_digit()))
if !is_codeblock && l != '' && nl != '' && !is_list
&& !nl.trim_left('\x01').trim_space().starts_with('```') {
merged_lines << '${l} ${nl}'
i++
continue
}
merged_lines << l
}
merged_lines.join_lines()
} else {
dn.merge_comments_without_examples()
}
mut renderer := markdown.HtmlRenderer{ mut renderer := markdown.HtmlRenderer{
transformer: &MdHtmlCodeHighlighter{ transformer: &MdHtmlCodeHighlighter{
table: tb table: tb
} }
} }
md_content := markdown.render(escaped_html, mut renderer) or { '' } md_content := markdown.render(dn.merge_comments_without_examples(), mut renderer) or { '' }
highlighted_code := html_highlight(dn.content, tb) highlighted_code := html_highlight(dn.content, tb)
node_class := if dn.kind == .const_group { ' const' } else { '' } node_class := if dn.kind == .const_group { ' const' } else { '' }
sym_name := get_sym_name(dn) sym_name := get_sym_name(dn)

119
cmd/tools/vdoc/tests/testdata/output_formats/main.ansi vendored
View File

@ -137,17 +137,17 @@ List point 3
import os import os
fn main() { fn main() {
dump(os.args) dump(os.args)
dump(os.args.len) dump(os.args.len)
assert os.args.len > 0 assert os.args.len > 0
// Test escape characters like for `&` and `<` // Test escape characters like for `&` and `<`
mut arr := [1, 2, 3] mut arr := [1, 2, 3]
mut ref := &arr mut ref := &arr
arr << 4 arr << 4
ch := chan bool{cap: 1} ch := chan bool{cap: 1}
ch <- true ch <- true
} }
``` ```
@ -161,42 +161,42 @@ List point 3
import time import time
struct JwtHeader { struct JwtHeader {
alg string alg string
typ string typ string
} }
struct JwtPayload { struct JwtPayload {
sub string sub string
name string name string
iat int iat int
} }
fn main() { fn main() {
sw := time.new_stopwatch() sw := time.new_stopwatch()
secret := 'your-256-bit-secret' secret := 'your-256-bit-secret'
token := make_token(secret) token := make_token(secret)
ok := auth_verify(secret, token) ok := auth_verify(secret, token)
dt := sw.elapsed().microseconds() dt := sw.elapsed().microseconds()
println('token: ${token}') println('token: ${token}')
println('auth_verify(secret, token): ${ok}') println('auth_verify(secret, token): ${ok}')
println('Elapsed time: ${dt} uS') println('Elapsed time: ${dt} uS')
} }
fn make_token(secret string) string { fn make_token(secret string) string {
header := base64.url_encode(json.encode(JwtHeader{'HS256', 'JWT'}).bytes()) header := base64.url_encode(json.encode(JwtHeader{'HS256', 'JWT'}).bytes())
payload := base64.url_encode(json.encode(JwtPayload{'1234567890', 'John Doe', 1516239022}).bytes()) payload := base64.url_encode(json.encode(JwtPayload{'1234567890', 'John Doe', 1516239022}).bytes())
signature := base64.url_encode(hmac.new(secret.bytes(), '${header}.${payload}'.bytes(), signature := base64.url_encode(hmac.new(secret.bytes(), '${header}.${payload}'.bytes(),
sha256.sum, sha256.block_size)) sha256.sum, sha256.block_size))
jwt := '${header}.${payload}.${signature}' jwt := '${header}.${payload}.${signature}'
return jwt return jwt
} }
fn auth_verify(secret string, token string) bool { fn auth_verify(secret string, token string) bool {
token_split := token.split('.') token_split := token.split('.')
signature_mirror := hmac.new(secret.bytes(), '${token_split[0]}.${token_split[1]}'.bytes(), signature_mirror := hmac.new(secret.bytes(), '${token_split[0]}.${token_split[1]}'.bytes(),
sha256.sum, sha256.block_size) sha256.sum, sha256.block_size)
signature_from_token := base64.url_decode(token_split[2]) signature_from_token := base64.url_decode(token_split[2])
return hmac.equal(signature_from_token, signature_mirror) return hmac.equal(signature_from_token, signature_mirror)
} }
``` ```
@ -207,12 +207,12 @@ List point 3
#include <map> #include <map>
std::map<std::string, int> my_map { std::map<std::string, int> my_map {
{"KEY_1", 0}, {"KEY_1", 0},
{"KEY_2", 10}, {"KEY_2", 10},
}; };
for (const auto &[key, value] : my_map) { for (const auto &[key, value] : my_map) {
std::cout << key << ": " << value << ", "; std::cout << key << ": " << value << ", ";
} }
std::cout << "\n"; std::cout << "\n";
``` ```
@ -227,27 +227,27 @@ List point 3
```v ```v
const html = '<!DOCTYPE html> const html = '<!DOCTYPE html>
<html lang="en"> <html lang="en">
<head> <head>
<style> <style>
body { body {
background: linear-gradient(to right, #274060, #1B2845); background: linear-gradient(to right, #274060, #1B2845);
color: GhostWhite; color: GhostWhite;
font-family: sans-serif; font-family: sans-serif;
text-align: center; text-align: center;
} }
</style> </style>
</head> </head>
<body> <body>
<h1>Your App Content!</h1> <h1>Your App Content!</h1>
<button onclick="callV()">Call V!</button> <button onclick="callV()">Call V!</button>
</body> </body>
<script> <script>
async function callV() { async function callV() {
// Call a V function that takes an argument and returns a value. // Call a V function that takes an argument and returns a value.
const res = await window.my_v_func(\'Hello from JS!\'); const res = await window.my_v_func(\'Hello from JS!\');
console.log(res); console.log(res);
} }
</script> </script>
</html>' </html>'
``` ```
@ -255,7 +255,10 @@ List point 3
- List point 2 - List point 2
- List point 3 - List point 3
1. Numbered markdown list point 1 2. List point 2 3. List point 3 1. Numbered markdown list point 1
2. List point 2
3. List point 3
const omega = 3 // should be first const omega = 3 // should be first
const alpha = 5 // should be in the middle const alpha = 5 // should be in the middle

119
cmd/tools/vdoc/tests/testdata/output_formats/main.text vendored
View File

@ -17,17 +17,17 @@ module main
import os import os
fn main() { fn main() {
dump(os.args) dump(os.args)
dump(os.args.len) dump(os.args.len)
assert os.args.len > 0 assert os.args.len > 0
// Test escape characters like for `&` and `<` // Test escape characters like for `&` and `<`
mut arr := [1, 2, 3] mut arr := [1, 2, 3]
mut ref := &arr mut ref := &arr
arr << 4 arr << 4
ch := chan bool{cap: 1} ch := chan bool{cap: 1}
ch <- true ch <- true
} }
``` ```
@ -41,42 +41,42 @@ module main
import time import time
struct JwtHeader { struct JwtHeader {
alg string alg string
typ string typ string
} }
struct JwtPayload { struct JwtPayload {
sub string sub string
name string name string
iat int iat int
} }
fn main() { fn main() {
sw := time.new_stopwatch() sw := time.new_stopwatch()
secret := 'your-256-bit-secret' secret := 'your-256-bit-secret'
token := make_token(secret) token := make_token(secret)
ok := auth_verify(secret, token) ok := auth_verify(secret, token)
dt := sw.elapsed().microseconds() dt := sw.elapsed().microseconds()
println('token: ${token}') println('token: ${token}')
println('auth_verify(secret, token): ${ok}') println('auth_verify(secret, token): ${ok}')
println('Elapsed time: ${dt} uS') println('Elapsed time: ${dt} uS')
} }
fn make_token(secret string) string { fn make_token(secret string) string {
header := base64.url_encode(json.encode(JwtHeader{'HS256', 'JWT'}).bytes()) header := base64.url_encode(json.encode(JwtHeader{'HS256', 'JWT'}).bytes())
payload := base64.url_encode(json.encode(JwtPayload{'1234567890', 'John Doe', 1516239022}).bytes()) payload := base64.url_encode(json.encode(JwtPayload{'1234567890', 'John Doe', 1516239022}).bytes())
signature := base64.url_encode(hmac.new(secret.bytes(), '${header}.${payload}'.bytes(), signature := base64.url_encode(hmac.new(secret.bytes(), '${header}.${payload}'.bytes(),
sha256.sum, sha256.block_size)) sha256.sum, sha256.block_size))
jwt := '${header}.${payload}.${signature}' jwt := '${header}.${payload}.${signature}'
return jwt return jwt
} }
fn auth_verify(secret string, token string) bool { fn auth_verify(secret string, token string) bool {
token_split := token.split('.') token_split := token.split('.')
signature_mirror := hmac.new(secret.bytes(), '${token_split[0]}.${token_split[1]}'.bytes(), signature_mirror := hmac.new(secret.bytes(), '${token_split[0]}.${token_split[1]}'.bytes(),
sha256.sum, sha256.block_size) sha256.sum, sha256.block_size)
signature_from_token := base64.url_decode(token_split[2]) signature_from_token := base64.url_decode(token_split[2])
return hmac.equal(signature_from_token, signature_mirror) return hmac.equal(signature_from_token, signature_mirror)
} }
``` ```
@ -87,12 +87,12 @@ module main
#include <map> #include <map>
std::map<std::string, int> my_map { std::map<std::string, int> my_map {
{"KEY_1", 0}, {"KEY_1", 0},
{"KEY_2", 10}, {"KEY_2", 10},
}; };
for (const auto &[key, value] : my_map) { for (const auto &[key, value] : my_map) {
std::cout << key << ": " << value << ", "; std::cout << key << ": " << value << ", ";
} }
std::cout << "\n"; std::cout << "\n";
``` ```
@ -107,27 +107,27 @@ module main
```v ```v
const html = '<!DOCTYPE html> const html = '<!DOCTYPE html>
<html lang="en"> <html lang="en">
<head> <head>
<style> <style>
body { body {
background: linear-gradient(to right, #274060, #1B2845); background: linear-gradient(to right, #274060, #1B2845);
color: GhostWhite; color: GhostWhite;
font-family: sans-serif; font-family: sans-serif;
text-align: center; text-align: center;
} }
</style> </style>
</head> </head>
<body> <body>
<h1>Your App Content!</h1> <h1>Your App Content!</h1>
<button onclick="callV()">Call V!</button> <button onclick="callV()">Call V!</button>
</body> </body>
<script> <script>
async function callV() { async function callV() {
// Call a V function that takes an argument and returns a value. // Call a V function that takes an argument and returns a value.
const res = await window.my_v_func(\'Hello from JS!\'); const res = await window.my_v_func(\'Hello from JS!\');
console.log(res); console.log(res);
} }
</script> </script>
</html>' </html>'
``` ```
@ -135,7 +135,10 @@ module main
- List point 2 - List point 2
- List point 3 - List point 3
1. Numbered markdown list point 1 2. List point 2 3. List point 3 1. Numbered markdown list point 1
2. List point 2
3. List point 3
const omega = 3 // should be first const omega = 3 // should be first
const alpha = 5 // should be in the middle const alpha = 5 // should be in the middle

11
vlib/v/doc/utils.v
View File

@ -63,9 +63,11 @@ pub fn merge_doc_comments(comments []DocComment) string {
mut comment := '' mut comment := ''
mut next_on_newline := true mut next_on_newline := true
mut is_codeblock := false mut is_codeblock := false
mut trimmed_indent := ''
for cmt in doc_comments.reverse() { for cmt in doc_comments.reverse() {
line_loop: for line in cmt.split_into_lines() { line_loop: for line in cmt.split_into_lines() {
l := line.trim_left('\x01').trim_space() l_normalized := line.trim_left('\x01')
l := l_normalized.trim_space()
last_ends_with_lb := comment.ends_with('\n') last_ends_with_lb := comment.ends_with('\n')
if l == '' { if l == '' {
comment += if last_ends_with_lb { '\n' } else { '\n\n' } comment += if last_ends_with_lb { '\n' } else { '\n\n' }
@ -74,7 +76,7 @@ pub fn merge_doc_comments(comments []DocComment) string {
} }
has_codeblock_quote := l.starts_with('```') has_codeblock_quote := l.starts_with('```')
if is_codeblock { if is_codeblock {
comment += l + '\n' comment += l_normalized.trim_string_left(trimmed_indent) + '\n'
if has_codeblock_quote { if has_codeblock_quote {
is_codeblock = !is_codeblock is_codeblock = !is_codeblock
} }
@ -86,11 +88,14 @@ pub fn merge_doc_comments(comments []DocComment) string {
} }
comment += l + '\n' comment += l + '\n'
is_codeblock = !is_codeblock is_codeblock = !is_codeblock
trimmed_indent = l_normalized.all_before(l)
next_on_newline = true next_on_newline = true
continue continue
} }
is_list := l.len > 1 && ((l[1] == ` ` && l[0] in [`-`, `*`, `+`])
|| (l.len > 2 && l[2] == ` ` && l[1] == `.` && l[0].is_digit()))
line_before_spaces := l.before(' ') line_before_spaces := l.before(' ')
if (l.starts_with('|') && l.ends_with('|')) || l.starts_with('- ') if is_list || (l.starts_with('|') && l.ends_with('|'))
|| (l.starts_with('#') && line_before_spaces.count('#') == line_before_spaces.len) { || (l.starts_with('#') && line_before_spaces.count('#') == line_before_spaces.len) {
comment += l + '\n' comment += l + '\n'
next_on_newline = true next_on_newline = true