From 980912dc963f31df5799ba3491be01afb7adc692 Mon Sep 17 00:00:00 2001 From: Turiiya <34311583+ttytm@users.noreply.github.com> Date: Wed, 22 Nov 2023 14:27:31 +0100 Subject: [PATCH] doc: update linebreak logic, handle "highlight-comments" (#19967) --- .../testdata/multiline/main.comments.out | 37 ++++++++++++++++- .../vdoc/tests/testdata/multiline/main.out | 5 +++ .../vdoc/tests/testdata/multiline/main.v | 41 ++++++++++++++++++- .../tests/testdata/newlines/main.comments.out | 3 +- cmd/tools/vdoc/tests/testdata/newlines/main.v | 4 +- cmd/tools/vdoc/theme/doc.css | 2 + vlib/v/doc/utils.v | 33 +++++++++------ 7 files changed, 107 insertions(+), 18 deletions(-) diff --git a/cmd/tools/vdoc/tests/testdata/multiline/main.comments.out b/cmd/tools/vdoc/tests/testdata/multiline/main.comments.out index 793abf13205098..2215f29cb0e1f5 100644 --- a/cmd/tools/vdoc/tests/testdata/multiline/main.comments.out +++ b/cmd/tools/vdoc/tests/testdata/multiline/main.comments.out @@ -5,5 +5,40 @@ fn a1() fn a2() this should be merged into the same line fn a3() - This should be its own parapgraph, because it ends with a dot. + This should be its own parapgraph. + This should be another paragraph. +fn a4() + This should be merged into one parapgraph. + + Note: this should be it's own paragraph. +fn a5() + This should be its own parapgraph. + + Note: this should also be it own paragraph + + Note: this should be it's own paragraph. +fn a6() + A comment + + Fixme: this should be it's own paragraph. + + Fixme: this should be it's own paragraph. + + Fixme: this should be it's own paragraph. +fn a7() + A comment + + Todo: this should be it's own paragraph. + + Todo: this should be it's own paragraph. + + Todo: this should be it's own paragraph. +fn a8() + A comment + + Todo: this should be it's own paragraph. + + Note: this should be it's own paragraph. + + Fixme: this should be it's own paragraph. diff --git a/cmd/tools/vdoc/tests/testdata/multiline/main.out b/cmd/tools/vdoc/tests/testdata/multiline/main.out index 4a3c36b9f15f3f..ce4906053f9a16 100644 --- a/cmd/tools/vdoc/tests/testdata/multiline/main.out +++ b/cmd/tools/vdoc/tests/testdata/multiline/main.out @@ -3,3 +3,8 @@ module main fn a1() fn a2() fn a3() +fn a4() +fn a5() +fn a6() +fn a7() +fn a8() diff --git a/cmd/tools/vdoc/tests/testdata/multiline/main.v b/cmd/tools/vdoc/tests/testdata/multiline/main.v index 840ca437212c5b..5dc5002126c568 100644 --- a/cmd/tools/vdoc/tests/testdata/multiline/main.v +++ b/cmd/tools/vdoc/tests/testdata/multiline/main.v @@ -9,8 +9,47 @@ pub fn a2() { println('hi') } -// This should be its own parapgraph, because it ends with a dot. +// This should be its own parapgraph. +// // This should be another paragraph. pub fn a3() { println('hi') } + +// This should be merged +// into one parapgraph. +// Note: this should be it's own paragraph. +pub fn a4() { + println('hi') +} + +// This should be its own parapgraph. +// NOTE: this should also be it own paragraph +// note: this should be it's own paragraph. +pub fn a5() { + println('hi') +} + +// A comment +// Fixme: this should be it's own paragraph. +// fixme: this should be it's own paragraph. +// FIXME: this should be it's own paragraph. +pub fn a6() { + println('hi') +} + +// A comment +// TODO: this should be it's own paragraph. +// todo: this should be it's own paragraph. +// Todo: this should be it's own paragraph. +pub fn a7() { + println('hi') +} + +// A comment +// TODO: this should be it's own paragraph. +// NOTE: this should be it's own paragraph. +// FIXME: this should be it's own paragraph. +pub fn a8() { + println('hi') +} diff --git a/cmd/tools/vdoc/tests/testdata/newlines/main.comments.out b/cmd/tools/vdoc/tests/testdata/newlines/main.comments.out index d25b9bff242ff1..f8770026176eba 100644 --- a/cmd/tools/vdoc/tests/testdata/newlines/main.comments.out +++ b/cmd/tools/vdoc/tests/testdata/newlines/main.comments.out @@ -3,8 +3,7 @@ module main fn funky() hello - empty line - newline using a full stop. + line after empty line, newline after commentline. ```v code ``` diff --git a/cmd/tools/vdoc/tests/testdata/newlines/main.v b/cmd/tools/vdoc/tests/testdata/newlines/main.v index 1c93d8512a8da9..8697bab1809ae7 100644 --- a/cmd/tools/vdoc/tests/testdata/newlines/main.v +++ b/cmd/tools/vdoc/tests/testdata/newlines/main.v @@ -1,7 +1,7 @@ // hello // -// empty line -// newline using a full stop. +// line after empty line, +// newline after commentline. // ```v // code // ``` diff --git a/cmd/tools/vdoc/theme/doc.css b/cmd/tools/vdoc/theme/doc.css index fc351983baf778..bfa76839f26e28 100644 --- a/cmd/tools/vdoc/theme/doc.css +++ b/cmd/tools/vdoc/theme/doc.css @@ -408,6 +408,8 @@ hr { font-size: 1rem; line-height: 1.6; letter-spacing: 0.025em; + max-width: 100ch; + word-wrap: break-word; } .doc-content a { color: #2779bd; diff --git a/vlib/v/doc/utils.v b/vlib/v/doc/utils.v index 7df612efe8910e..1ab660d36cd8e4 100644 --- a/vlib/v/doc/utils.v +++ b/vlib/v/doc/utils.v @@ -69,19 +69,31 @@ pub fn merge_doc_comments(comments []DocComment) string { } commentlines = commentlines.reverse() mut is_codeblock := false - mut previously_newline := true + mut next_on_newline := true mut comment := '' for line in commentlines { if line.starts_with('```') { is_codeblock = !is_codeblock - comment = comment + '\n' + line + comment += '\n' + line continue } else if is_codeblock { - comment = comment + '\n' + line + comment += '\n' + line continue } - line_trimmed := line.trim(' ') + line_trimmed := line.trim(' ').to_lower() + + // Use own paragraph for "highlight" comments. + if line_trimmed.starts_with('note:') { + comment += '\n\nNote:${line['note:'.len..]}' + continue + } else if line_trimmed.starts_with('fixme:') { + comment += '\n\nFixme:${line['fixme:'.len..]}' + continue + } else if line_trimmed.starts_with('todo:') { + comment += '\n\nTodo:${line['todo:'.len..]}' + continue + } mut is_horizontalrule := false line_no_spaces := line_trimmed.replace(' ', '') @@ -97,15 +109,12 @@ pub fn merge_doc_comments(comments []DocComment) string { || (line.starts_with('#') && line.before(' ').count('#') == line.before(' ').len) || (line_trimmed.starts_with('|') && line_trimmed.ends_with('|')) || line_trimmed.starts_with('- ') { - comment = comment + '\n' + line - previously_newline = true - } else if line.ends_with('.') { - comment = comment + '\n' + line + ' ' - previously_newline = true + comment += '\n' + line + next_on_newline = true } else { - sep := if previously_newline { '\n' } else { ' ' } - comment = comment + sep + line - previously_newline = false + sep := if next_on_newline { '\n' } else { ' ' } + comment += sep + line + next_on_newline = false } } return comment