fix: read only \/*!\ as QDoc, and cover commands

Signed-off-by: Joseph Kato <joseph@jdkato.io>

Author: jdkato

internal/lint/fragment.go

@@ -101,9 +101,9 @@ func (l *Linter) lintFragments(f *core.File) error {
 
 	last := 0
 	for _, comment := range comments {
-		// QDoc is written in block comments; a `//` comment is code, not
-		// documentation.
-		if f.NormedExt == ".qdoc" && !strings.HasPrefix(comment.Source, "/*") {
+		// QDoc reads `/*! ... */` only; a `//` line comment or a plain
+		// `/* ... */` block is code, not documentation.
+		if f.NormedExt == ".qdoc" && !strings.HasPrefix(comment.Source, "/*!") {
 			continue
 		}
 

internal/lint/qdoc.go

@@ -27,21 +27,31 @@ var qdocVerbatim = map[string]struct{}{
 	"raw":     {},
 }
 
-// qdocSkipLine names the topic, context, and quoting commands whose whole
-// line is markup: identifiers, file paths, and cross-references, not prose.
+// qdocSkipLine names the topic, context, quoting, build-system, and
+// conditional commands whose whole line is markup: identifiers, file paths,
+// cross-references, and expressions, not prose.
 var qdocSkipLine = map[string]struct{}{
 	"annotatedlist":       {},
 	"class":               {},
+	"cmakecomponent":      {},
+	"cmakepackage":        {},
+	"cmaketargetitem":     {},
 	"codeline":            {},
+	"compareswith":        {},
 	"contentspage":        {},
+	"dontdocument":        {},
 	"dots":                {},
+	"else":                {},
+	"endcompareswith":     {},
+	"endif":               {},
 	"enum":                {},
 	"example":             {},
 	"externalpage":        {},
 	"fn":                  {},
 	"generatelist":        {},
 	"group":               {},
 	"headerfile":          {},
+	"if":                  {},
 	"include":             {},
 	"indexpage":           {},
 	"ingroup":             {},
@@ -55,6 +65,7 @@ var qdocSkipLine = map[string]struct{}{
 	"meta":                {},
 	"module":              {},
 	"namespace":           {},
+	"nativetype":          {},
 	"nextpage":            {},
 	"noautolist":          {},
 	"nonreentrant":        {},
@@ -69,12 +80,17 @@ var qdocSkipLine = map[string]struct{}{
 	"qmlattachedsignal":   {},
 	"qmlbasictype":        {},
 	"qmlclass":            {},
+	"qmlenum":             {},
 	"qmlmethod":           {},
 	"qmlmodule":           {},
 	"qmlproperty":         {},
 	"qmlsignal":           {},
+	"qmlsingletontype":    {},
 	"qmltype":             {},
 	"qmlvaluetype":        {},
+	"qtcmakepackage":      {},
+	"qtcmaketargetitem":   {},
+	"qtvariable":          {},
 	"quotefile":           {},
 	"quotefromfile":       {},
 	"reentrant":           {},
@@ -88,8 +104,10 @@ var qdocSkipLine = map[string]struct{}{
 	"skipuntil":           {},
 	"snippet":             {},
 	"startpage":           {},
+	"tableofcontents":     {},
 	"target":              {},
 	"threadsafe":          {},
+	"typealias":           {},
 	"typedef":             {},
 	"variable":            {},
 	"wrapper":             {},
@@ -109,9 +127,11 @@ var (
 	qdocBlockCmd = regexp.MustCompile(`^\s*\\([a-zA-Z0-9]+)\s*(.*)$`)
 	// An inline command and its argument: `\c word` or `\c {some words}`,
 	// with an optional [qualifier] for `\l`. A braced argument may wrap
-	// within its paragraph.
-	qdocInlineCmd = regexp.MustCompile(`\\([a-zA-Z0-9]+)\s*(\[[^\]\n]*\]\s*)?(\{[^{}]*\}|[^\s{][^\s]*)?`)
-	// The braced {text} that may follow a braced `\l` target.
+	// within its paragraph. `\\` is an escaped backslash, matched first so
+	// that the command that follows one is read as text.
+	qdocInlineCmd = regexp.MustCompile(`\\\\|\\([a-zA-Z0-9]+)\s*(\[[^\]\n]*\]\s*)?(\{[^{}]*\}|[^\s{][^\s]*)?`)
+	// The braced {text} that may follow a braced `\l` target or `\span`
+	// attribute.
 	qdocLinkText = regexp.MustCompile(`^\s*\{[^{}]*\}`)
 )
 
@@ -144,6 +164,13 @@ func qdocInline(text string) string {
 		}
 		out.WriteString(text[:loc[0]])
 
+		if loc[2] < 0 {
+			// `\\` is a literal backslash, not a command.
+			out.WriteString(`\`)
+			text = text[loc[1]:]
+			continue
+		}
+
 		name := text[loc[2]:loc[3]]
 		arg := ""
 		if loc[6] >= 0 {
@@ -171,9 +198,20 @@ func qdocInline(text string) string {
 				}
 			}
 			out.WriteString(`<a href="#">` + label + "</a>")
+		case "span":
+			// `\span {class="x"} {text}`: the attribute is markup, the
+			// braced text that follows is prose.
+			label := ""
+			if m := qdocLinkText.FindString(rest); m != "" {
+				label = qdocArg(strings.TrimSpace(m))
+				rest = rest[len(m):]
+			}
+			out.WriteString("<span>" + label + "</span>")
 		case "image", "inlineimage":
 			// The argument is a file name; a caption, if any, follows as
 			// ordinary prose.
+		case "unicode":
+			// The argument is a code point, not prose.
 		default:
 			// An unknown command is markup; whatever followed it is prose.
 			rest = text[loc[3]:]
@@ -270,14 +308,24 @@ func (c *qdocConv) endItem() {
 	top.inItem = false
 }
 
+// qdocBlankDelims blanks the comment delimiters of a standalone .qdoc file,
+// which a command or its prose may share a line with: `/*! \page index.html`.
+// They are replaced by spaces rather than removed so that a column in the
+// converted line is still a column in the source.
+func qdocBlankDelims(raw string) string {
+	if i := strings.Index(raw, "/*!"); i >= 0 && strings.TrimSpace(raw[:i]) == "" {
+		raw = raw[:i] + "   " + raw[i+3:]
+	}
+	if i := strings.LastIndex(raw, "*/"); i >= 0 && strings.TrimSpace(raw[i+2:]) == "" {
+		raw = raw[:i] + "  " + raw[i+2:]
+	}
+	return raw
+}
+
 func (c *qdocConv) line(raw string) { //nolint:gocyclo // one case per command family
+	raw = qdocBlankDelims(raw)
 	trimmed := strings.TrimSpace(raw)
 
-	// Comment delimiters, in both standalone .qdoc files and sources.
-	if trimmed == "/*!" || trimmed == "*/" || strings.HasPrefix(trimmed, "/*!") && strings.HasSuffix(trimmed, "*/") {
-		return
-	}
-
 	if c.verbatim != "" {
 		if m := qdocBlockCmd.FindStringSubmatch(raw); m != nil && m[1] == c.verbatim {
 			c.verbatim = ""

internal/lint/qdoc_test.go

@@ -114,6 +114,65 @@ func TestQdocHTML(t *testing.T) {
 			[]string{"The  rest of the sentence."},
 			[]string{"unknowncmd"},
 		},
+		{
+			"a command may share the opening delimiter's line",
+			"/*! \\page overview.html\n    \\title The Page Title\n*/\n",
+			[]string{"<h1>The Page Title</h1>"},
+			[]string{"/*!", "*/", "overview"},
+		},
+		{
+			"prose may share the opening delimiter's line",
+			"/*! One brief sentence. */\n",
+			[]string{"One brief sentence."},
+			[]string{"/*!", "*/"},
+		},
+		{
+			"adjacent comment blocks are separate paragraphs",
+			"/*!\n    First block.\n*/\n\n/*!\n    Second block.\n*/\n",
+			[]string{"<p>    First block.</p>", "<p>    Second block.</p>"},
+			nil,
+		},
+		{
+			"build-system and type commands are markup",
+			"\\qmlenum Mode\n\\qmlsingletontype Theme\n\\typealias Alias\n" +
+				"\\nativetype QString\n\\cmakepackage Qt6\n\\cmakecomponent Widgets\n" +
+				"\\cmaketargetitem Target\n\\qtcmakepackage Core\n" +
+				"\\qtcmaketargetitem Item\n\\qtvariable widgets\n" +
+				"\\tableofcontents auto\n\\dontdocument (Hidden)\n\nProse here.\n",
+			[]string{"<p>Prose here.</p>"},
+			[]string{"Mode", "Theme", "Alias", "QString", "Qt6", "Widgets",
+				"Target", "Core", "Item", "widgets", "auto", "Hidden"},
+		},
+		{
+			"a comparison block's command lines are markup",
+			"\\compareswith equality QAnyStringView\n\\endcompareswith\n\nProse here.\n",
+			[]string{"<p>Prose here.</p>"},
+			[]string{"QAnyStringView"},
+		},
+		{
+			"a conditional's expression is markup, its branches prose",
+			"\\if defined(onlinedocs)\nOnline prose.\n\\else\nOffline prose.\n\\endif\n",
+			[]string{"Online prose.", "Offline prose."},
+			[]string{"onlinedocs"},
+		},
+		{
+			"an escaped backslash is text, not a command",
+			"Write \\\\c to show the command.\n",
+			[]string{`Write \c to show the command.`},
+			[]string{"<code>"},
+		},
+		{
+			"a unicode code point is markup",
+			"A bullet \\unicode 0x2022 sits here.\n",
+			[]string{"A bullet", "sits here."},
+			[]string{"0x2022"},
+		},
+		{
+			"a span's attribute is markup, its text prose",
+			"See \\span {class=\"vrheader\"} {the spanned words} here.\n",
+			[]string{"<span>the spanned words</span>", "here."},
+			[]string{"vrheader", "class="},
+		},
 	}
 
 	for _, c := range cases {

testdata/e2e/lint.yaml

@@ -348,7 +348,9 @@ cases:
   - name: qdoc
     about: "#784 -- QDoc's commands are markup: topic lines, code blocks,
       links' targets, and options say nothing, while titles, sections,
-      briefs, notes, items, cells, and captions are prose"
+      briefs, notes, items, cells, and captions are prose. A command may
+      share the opening `/*!` line, and a conditional block's prose still
+      counts"
     args: test.qdoc
     exit: 0
     want: |
@@ -364,14 +366,18 @@ cases:
       test.qdoc:33:36:vale.Annotations:'TODO' left in text
       test.qdoc:36:46:vale.Annotations:'XXX' left in text
       test.qdoc:38:47:vale.Annotations:'TODO' left in text
+      test.qdoc:48:34:vale.Annotations:'TODO' left in text
+      test.qdoc:67:37:vale.Annotations:'XXX' left in text
+      test.qdoc:69:27:vale.Annotations:'TODO' left in text
+      test.qdoc:73:61:vale.Annotations:'XXX' left in text
     absent:
       - FIXME
       - NOTE
 
   - name: qdoc-fragments
     about: doc comments in C++ sources lint as QDoc through `[formats]`, with
-      alerts mapped back to the source; block comments are documentation,
-      line comments are code
+      alerts mapped back to the source; only `/*!` is documentation, while
+      line comments and plain block comments are code
     files:
       .vale.ini: |
         StylesPath = styles
@@ -404,15 +410,18 @@ cases:
         // A ZQX in a line comment is code, not documentation.
 
         /*
-            A plain block comment still has its ZQX linted.
+            A plain block comment with a ZQX is code too.
         */
+
+        /****************************************************
+        ** A ZQX in a license header is not documentation.
+        ****************************************************/
         void Widget::other() {}
     args: widget.cpp
     exit: 1
     want: |
       widget.cpp:6:23:T.Tok:'ZQX' in a doc comment
       widget.cpp:8:26:T.Tok:'ZQX' in a doc comment
-      widget.cpp:15:41:T.Tok:'ZQX' in a doc comment
 
   - name: qml-fragments
     about: doc comments in QML sources lint as QDoc through `[formats]`;
@@ -471,7 +480,7 @@ cases:
             //! [0]
 
             /*
-                A ZQX in a plain block comment still lints.
+                A ZQX in a plain block comment is code as well.
             */
             function formatValue(v) {
                 var label = "a ZQX in a string is code";
@@ -491,7 +500,6 @@ cases:
       Slider.qml:10:17:T.Tok:'ZQX' in a doc comment
       Slider.qml:16:13:T.Note:'ZQX' in a note
       Slider.qml:16:13:T.Tok:'ZQX' in a doc comment
-      Slider.qml:27:11:T.Tok:'ZQX' in a doc comment
       Slider.qml:36:29:T.Tok:'ZQX' in a doc comment
 
   - name: quarto

testdata/fixtures/formats/test.qdoc

@@ -43,3 +43,32 @@
 
     \sa FIXME, QObject
 */
+
+/*! \page conditional.html
+    \title A second title with a TODO in it
+
+    \qmlenum Mode
+    \qmlsingletontype FIXME
+    \typealias FIXME
+    \nativetype FIXME
+    \cmakepackage FIXME
+    \cmakecomponent FIXME
+    \cmaketargetitem FIXME
+    \qtcmakepackage FIXME
+    \qtcmaketargetitem FIXME
+    \qtvariable FIXME
+    \tableofcontents FIXME
+    \dontdocument (FIXME)
+
+    \compareswith equality FIXME
+    \endcompareswith
+
+    \if defined(FIXME)
+    A conditional paragraph with an XXX in it.
+    \else
+    Another branch with a TODO in it.
+    \endif
+
+    A literal backslash \\c is not a command, and \unicode 0x2022 is a
+    character. \span {class="FIXME"} {Spanned prose with an XXX in it.}
+*/