fix: treat a snippet marker inside a QDoc comment as markup

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

Author: jdkato

internal/lint/qdoc.go

@@ -425,6 +425,13 @@ func (c *qdocConv) line(raw string) { //nolint:gocyclo // one case per command f
 		return
 	}
 
+	// A `//` line inside a comment is a snippet marker -- `//! [intro]` --
+	// or code, never prose. QDoc renders nothing for it, so it does not end
+	// the paragraph it sits in the middle of either.
+	if strings.HasPrefix(trimmed, "//") {
+		return
+	}
+
 	if trimmed == "" {
 		c.closeDiv()
 		c.flush()

internal/lint/qdoc_test.go

@@ -110,6 +110,12 @@ func TestQdocHTML(t *testing.T) {
 				`<data class="anchor">Another Anchor</data>`, "<p>Prose here.</p>"},
 			[]string{"\\target", "\\keyword"},
 		},
+		{
+			"a snippet marker is markup, and does not break its paragraph",
+			"/*!\n    Prose one.\n//! [intro]\n    Prose two.\n*/\n",
+			[]string{"Prose one.", "Prose two."},
+			[]string{"intro", "//!"},
+		},
 		{
 			"sa lines are markup",
 			"Prose here.\n\n\\sa QWidget, QObject\n",

testdata/e2e/lint.yaml

@@ -351,7 +351,7 @@ cases:
       briefs, notes, items, cells, and captions are prose. A command may
       share the opening `/*!` line; a conditional block's prose, a
       deprecation's advice, and a summary still count; and modifiers, cell
-      spans, and version qualifiers say nothing"
+      spans, version qualifiers, and snippet markers say nothing"
     args: test.qdoc
     exit: 0
     want: |
@@ -378,6 +378,8 @@ cases:
       test.qdoc:105:53:vale.Annotations:'TODO' left in text
       test.qdoc:108:35:vale.Annotations:'XXX' left in text
       test.qdoc:108:70:vale.Annotations:'TODO' left in text
+      test.qdoc:113:45:vale.Annotations:'TODO' left in text
+      test.qdoc:116:51:vale.Annotations:'XXX' left in text
     absent:
       - FIXME
       - NOTE

testdata/fixtures/formats/test.qdoc

@@ -107,3 +107,11 @@
 
     Use \bold {bold prose with an XXX in it} and \i {emphasis with a TODO}.
 */
+
+/*!
+//! [intro]
+    A snippet marker holds no prose, and no TODO of its own.
+//! [intro]
+
+    \image screenshot-FIXME.png A caption with an XXX in it.
+*/