fix: keep \vale off\ working when QDoc prose is escaped

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

Author: jdkato

internal/lint/qdoc.go

@@ -209,7 +209,30 @@ var qdocInlineNames = map[string]struct{}{
 // raw-text mode, so the rest of the page is swallowed looking for a close
 // that never comes. The tokenizer decodes these again, so the text a rule
 // sees, and the text located in the source, are unchanged.
-var qdocEsc = strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;").Replace
+var qdocEscAll = strings.NewReplacer("&", "&amp;", "<", "&lt;", ">", "&gt;").Replace
+
+// An HTML comment, which survives escaping: `vale off` and `vale on` reach
+// the walker as comments, and a QDoc file writes them the same way any other
+// markup does.
+var qdocHTMLComment = regexp.MustCompile(`(?s)<!--.*?-->`)
+
+func qdocEsc(text string) string {
+	spans := qdocHTMLComment.FindAllStringIndex(text, -1)
+	if spans == nil {
+		return qdocEscAll(text)
+	}
+
+	var out strings.Builder
+	last := 0
+	for _, s := range spans {
+		out.WriteString(qdocEscAll(text[last:s[0]]))
+		out.WriteString(text[s[0]:s[1]])
+		last = s[1]
+	}
+	out.WriteString(qdocEscAll(text[last:]))
+
+	return out.String()
+}
 
 // qdocArg strips the braces from a command argument.
 func qdocArg(arg string) string {

internal/lint/qdoc_test.go

@@ -122,6 +122,12 @@ func TestQdocHTML(t *testing.T) {
 			[]string{"using a &lt;script&gt; tag.", "<p>Prose after it.</p>"},
 			nil,
 		},
+		{
+			"an HTML comment survives escaping",
+			"A <!-- vale off --> toggle and a <script> tag.\n",
+			[]string{"<!-- vale off -->", "&lt;script&gt;"},
+			[]string{"&lt;!--"},
+		},
 		{
 			"sa lines are markup",
 			"Prose here.\n\n\\sa QWidget, QObject\n",

testdata/e2e/lint.yaml

@@ -481,6 +481,45 @@ cases:
       markers.qdoc:6:16:T.Mark:'MARKB'
       snippet.qdoc:7:17:T.Mark:'MARKA'
 
+  - name: qdoc-toggles
+    about: "`vale off` and `vale on` work in QDoc, as an HTML comment and
+      through `CommentDelimiters`, even though the prose around them may
+      talk about markup"
+    files:
+      .vale.ini: |
+        StylesPath = styles
+        MinAlertLevel = suggestion
+
+        [*.qdoc]
+        T.Tok = YES
+        CommentDelimiters = [[, ]]
+      styles/T/Tok.yml: |
+        extends: existence
+        message: "'%s'"
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      t.qdoc: |
+        /*!
+            A ZQX before, in a <script> tag sentence.
+
+            <!-- vale off -->
+            A ZQX an HTML comment suppresses.
+            <!-- vale on -->
+
+            [[ vale off ]]
+            A ZQX custom delimiters suppress.
+            [[ vale on ]]
+
+            A ZQX after.
+        */
+    args: t.qdoc
+    exit: 1
+    want: |
+      t.qdoc:2:7:T.Tok:'ZQX'
+      t.qdoc:12:7:T.Tok:'ZQX'
+
   - name: qdoc-classes
     about: "`.qdocinc` is QDoc without configuration, and `\\div` and `\\span`
       carry their class into the scope so a rule can target the prose they