fix: read a .qdocinc as the include it is, and keep meta out of prose

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

Author: jdkato

internal/lint/ast.go

@@ -278,7 +278,7 @@ func (l *Linter) lintScope(f *core.File, state *walker, txt string) error {
 	if core.StringInSlice("data", state.tagHistory) {
 		f.Metrics["meta"]++
 
-		b := state.block(txt, withClasses("meta", state)+f.MetaScope+f.RealExt, 0)
+		b := state.block(txt, withClasses("meta", state)+metaScope(f)+f.RealExt, 0)
 		return l.lintBlock(f, b, state.lines, 0, false)
 	}
 
@@ -399,6 +399,19 @@ func seek(s, text string, from int) (int, int) {
 // carrying no distinct tag can still be selected. An AsciiDoc block title is a
 // `<div class="title">`, indistinguishable from body text by tag alone, and
 // becomes `text.class.title` here. See #642.
+// metaScope is the context a fragment carries, with the `text` it opens with
+// taken off.
+//
+// MetaScope is appended to every block's scope, and a comment's is
+// `text.comment.line`. A selector matches on the set of sections a scope has,
+// so appending that to `meta` puts `text` back and an ordinary rule matches
+// the content `meta` exists to hold apart -- the same QDoc comment lints
+// differently in a `.qdoc` file, where there is no MetaScope, than in the C++
+// source it was written in. See #784.
+func metaScope(f *core.File) string {
+	return strings.TrimPrefix(f.MetaScope, ".text")
+}
+
 func withClasses(scope string, state *walker) string {
 	classes := state.classes()
 	if len(classes) == 0 {

internal/lint/qdoc.go

@@ -654,7 +654,16 @@ func qdocConvert(content string, inComment bool) string {
 }
 
 // lintQDoc lints a QDoc source: Qt's documentation markup.
+//
+// A `.qdocinc` is the exception. It is an include -- the body of a comment,
+// pulled into a document by `\include` -- so its markup is not wrapped in
+// `/*! ... */`, and reading it as a `.qdoc` file leaves the whole thing
+// unread while waiting for a comment to open. Starting inside one reads both
+// shapes: a `/*!` still opens a comment where the file writes one. See #784.
 func (l *Linter) lintQDoc(f *core.File) error {
+	if f.RealExt == ".qdocinc" {
+		return l.lintQDocWith(f, qdocFragmentToHTML)
+	}
 	return l.lintQDocWith(f, qdocToHTML)
 }
 

testdata/e2e/lint.yaml

@@ -702,6 +702,90 @@ cases:
       widget.cpp:6:23:T.Tok:'ZQX' in a doc comment
       widget.cpp:8:26:T.Tok:'ZQX' in a doc comment
 
+  - name: qdocinc-include
+    about: "a `.qdocinc` is an include, not a file of comments: its markup is
+      the body of one, so nothing waits for a `/*!` that the file never
+      writes, and a `//! [name]` marker is still markup"
+    files:
+      .vale.ini: |
+        StylesPath = styles
+        MinAlertLevel = suggestion
+
+        [*.qdocinc]
+        T.Tok = YES
+      styles/T/Tok.yml: |
+        extends: existence
+        message: "'%s'"
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      steps.qdocinc: |
+        //! [intro]
+            \note A ZQX in an included note.
+        //! [intro]
+
+        A ZQX in an included paragraph.
+      wrapped.qdocinc: |
+        /*!
+            A ZQX in an include that writes the comment out.
+        */
+    args: .
+    exit: 1
+    want: |
+      steps.qdocinc:2:13:T.Tok:'ZQX'
+      steps.qdocinc:5:3:T.Tok:'ZQX'
+      wrapped.qdocinc:2:7:T.Tok:'ZQX'
+
+  - name: qdoc-meta-in-source
+    about: "the same comment lints the same way wherever it is written: an
+      image file name is `meta` in a C++ source as much as in a `.qdoc` file,
+      so an ordinary rule passes over it and a `meta` rule reaches it"
+    files:
+      .vale.ini: |
+        StylesPath = styles
+        MinAlertLevel = suggestion
+
+        [formats]
+        cpp = qdoc
+
+        [*.{qdoc,cpp}]
+        T.Prose = YES
+        T.Image = YES
+      styles/T/Prose.yml: |
+        extends: existence
+        message: "'%s' as prose"
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      styles/T/Image.yml: |
+        extends: existence
+        message: "'%s' in a file name"
+        scope: meta.class.image
+        level: error
+        nonword: true
+        raw:
+          - ZQX
+      same.qdoc: |
+        /*!
+            \image ZQX-diagram.png A caption with a ZQX in it.
+        */
+      widget.cpp: |
+        #include "widget.h"
+
+        /*!
+            \image ZQX-diagram.png A caption with a ZQX in it.
+        */
+        void Widget::clicked() {}
+    args: .
+    exit: 1
+    want: |
+      same.qdoc:2:12:T.Image:'ZQX' in a file name
+      same.qdoc:2:45:T.Prose:'ZQX' as prose
+      widget.cpp:4:12:T.Image:'ZQX' in a file name
+      widget.cpp:4:45:T.Prose:'ZQX' as prose
+
   - name: qml-fragments
     about: doc comments in QML sources lint as QDoc through `[formats]`;
       the QML code itself -- objects, bindings, functions, strings, line