qt skill-vale-qdoc
Reference for the vale-qdoc fork — the patched Vale build with QDoc parser support. Covers file routing, scopes, config, and common lint issues.
File routing
| Extension | Linted by default | Notes |
|---|---|---|
.qdoc, .qdocinc |
Yes | Full QDoc markup pipeline |
.cpp, .qml |
Yes, with opt-in | Requires [formats] entry (see below) |
.h, .cxx, .cc |
No | Add via [formats] the same way as .cpp |
Standard Vale treats .qdoc and .qdocinc as plain text — always use the
patched build.
Enabling C++ and QML linting
Add to .vale-qdoc.ini:
[formats]
cpp = qdoc
qml = qdoc
h = qdoc
cxx = qdoc
Only /*!...*/ doc-comment blocks are routed through the QDoc pipeline.
Regular // and /* */ comments are skipped — they are not QDoc
documentation.
Scopes produced
Rules target specific QDoc commands via these scopes:
| Scope | QDoc command |
|---|---|
text.comment.heading |
\section1–\section6 |
text.comment.brief |
\brief |
text.comment.note |
\note |
text.comment.warning |
\warning |
text.comment.title |
\title |
text.comment.block |
General multi-line prose (enables sentence rules) |
text.comment.line |
General single-line text |
meta.image |
\image / \inlineimage filename (no alt text only) |
meta.anchor |
\target / \keyword argument |
meta.* scopes prevent prose rules (Vale.Terms, Microsoft.*) from
firing on image filenames and anchor identifiers.
Key caveats
Code block content is excluded
Text inside \code…\endcode, \badcode…\endcode, and
\qml…\endqml blocks is not linted. \badcode ends with \endcode,
not \endbadcode. \snippet has no end counterpart.
Sentence-scope rules require multi-line prose
Rules using scope: sentence (e.g. Microsoft.OxfordComma,
Microsoft.SentenceLength) only fire on text.comment.block — full prose
spanning a /*!...*/ block. They do not fire on single-line scopes
(heading, brief, title).
Duplicate alerts
Duplicate alerts for \brief, \note, and \warning were fixed in
v3.14.2-qdocsupport-alpha1. If duplicates appear for any command, report
them as a bug.
Generic Vale issues
For issues not specific to QDoc — config file resolution, StylesPath,
vale sync, exit codes, ls-config — see skill-vale
(skills/skill-vale/SKILL.md).
Common "rule not firing" causes
- Wrong extension —
.cpp/.qml/.hnot mapped in[formats]; file treated as plain C++ code, not QDoc. - Rule scoped too narrowly — a rule scoped to
text.comment.briefwill not fire ontext.comment.lineortext.comment.block. - Content inside a code block — excluded from linting by design.
- Sentence rule on a one-line brief —
scope: sentencerequires multi-line prose; single-line commands are not sentence-segmented. MinAlertLeveltoo high — check the rule'slevel:in its.ymlfile and compare againstMinAlertLevelin.vale-qdoc.ini.
Version History
- v1.0 (2026-03-30): Initial version
- File routing table for
.qdoc,.qdocinc,.cpp,.qml,.h,.cxx - Enabling C++ and QML linting via
[formats] - Scopes produced by the QDoc parser for all QDoc commands
meta.*scopes for image filenames and anchor identifiers- Key caveats: code block exclusion, sentence-scope rules, duplicate alerts
- Cross-reference to skill-vale for generic Vale issues
- Common "rule not firing" causes
- File routing table for