.vale-qdoc.ini - mozsearch

# Vale configuration for linting QDoc source files (.qdoc, .qdocinc, .qml, .cpp).

# NOTE: The IgnoredClasses, SkippedScopes, and IgnoredScopes settings below

# are placeholders from the HTML config and need to be adapted for QDoc sources.

# Core settings

StylesPath = styles

MinAlertLevel = suggestion #, warning or error

#A comma-separated list of CSS classes to ignore (HTML-specific — adapt for QDoc).

#IgnoredClasses = alignedsummary, fn, copy-notice, cpp, qml, footer, navigationbar, tblQmlPropNode

#A comma-separated list of HTML blocks to ignore (HTML-specific — adapt for QDoc).

#SkippedScopes = header, footer, script

#A comma-separated list of inline HTML elements to skip (HTML-specific — adapt for QDoc).

#IgnoredScopes = a,code,b

#Style packages from the github.com/errata-ai repo

#vale can sync these packages to ensure they are always

#up-to-date.

Packages = Microsoft

#Vocabulary containing the list of words that you either

#want to accept or reject. For more information about

#this, refer to: https://vale.sh/docs/topics/vocab/

Vocab = Qt, qul, Figma

[formats]

# Route .cpp through the QDoc fragment pipeline so that /*!...*/ doc-comment

# blocks get full QDoc-aware linting (heading/brief/title scopes and

# sentence rules). See lintQDocFragments in lint/fragment.go.

# Note: .qml is already mapped to QDoc() in GetLanguageFromExt and does not

# need a format association here.

cpp = qdoc

cxx = qdoc

h = qdoc

[*.{qdoc,qdocinc,cpp,qml,h,cxx}]

# Strip inline command tokens that would otherwise appear as prose.

# \c is NOT listed here: the upstream vale converts \c to <code>...</code> via

# qdocToHTML, and code spans are naturally skipped by the HTML walker. Listing

# \c in TokenIgnores would blank the argument (including any trailing period,

# e.g. "\c false.") before qdocToHTML runs, causing false positives where a

# brief ending in a \c-terminated sentence is reported as missing a period.

# \l is also NOT listed — it is a link_command converted to <a href=...> by

# qdocToHTML; the link text is linted correctly via the inline capture path.

# The final entry blanks qualified Qt module names (QtQuick.Layouts,

# QtQml.Models). Microsoft.Spacing matches [a-z][.?!][A-Z] and cannot

# tell the period in a module name from a sentence boundary, so it

# reports these as missing spaces. Keep the entry as narrow as

# possible: anything it blanks is invisible to every enabled rule,

# including Qt.Mechanics.Spelling.

TokenIgnores = \\meta[ \t]+.*, \\(?:snippet|include|quotefile|quotefromfile|codeline|printline|printto|printuntil|skipline|skipto|skipuntil|page|externalpage|example|headerfile|nextpage|previouspage|startpage|ingroup|annotatedlist|generatelist|nativetype|inqmlmodule|since|qtcmakepackage|qtvariable)[ \t]+\S+(?:[ \t]+\S+)?, Qt(?:Quick3D|Quick|Qml)(?:\.(?:Layouts|Controls|Material|Universal|Fusion|Imagine|iOS|Particles|Particles3D|Shapes|Timeline|Dialogs|LocalStorage|VirtualKeyboard|Settings|Scene2D|Scene3D|Models|XmlListModel|WorkerScript|Effects|Helpers))+

# Load all rules from the listed styles. Alternatively, enable individual

# rules below using Style.Rule = YES.

#BasedOnStyles = Microsoft, Qt

# Enable/disable each rule offered by the style

# Style.Rule = {YES, NO} to enable or disable a specific rule

Vale.Terms = YES

Vale.Avoid = YES

Microsoft.Foreign = YES

Microsoft.Avoid = YES

Microsoft.OxfordComma = YES

Microsoft.Passive = YES

Microsoft.Dashes = YES

# Microsoft.Spacing = YES  # replaced by Qt.Mechanics.Spacing (adds an exceptions list)

Microsoft.Wordiness = YES

Microsoft.We = YES

Microsoft.HeadingAcronyms = YES

Microsoft.HeadingColons = YES

Microsoft.HeadingPunctuation = YES

Microsoft.Headings = YES

Microsoft.SentenceLength = YES

Microsoft.Semicolon = YES

# Qt.Language: wording, grammar, tone, and terminology -- checks that judge

# how prose is phrased, independent of which QDoc element it appears in.

# See vale_linter_config/README.md and styles/Qt/Language/README.md.

Qt.Language.FutureTense = YES

Qt.Language.LatinTerms = YES

Qt.Language.LoseLoose = YES

Qt.Language.QDocPageTitle = YES

Qt.Language.QtTerminology = YES

Qt.Language.HedgingWords = YES

Qt.Language.WordyFillers = YES

Qt.Language.WordyQuantifier = YES  # extends Microsoft.Wordiness (swap+)

Qt.Language.WordyConstructions = YES

Qt.Language.Idioms = YES

# Experimental: demonstrated real false positives during testing (see

# styles/Qt/Language/README.md) -- left disabled pending a more precise design.

#Qt.Language.Numbers = YES           # flags version numbers ("Qt 6")

#Qt.Language.CausationSinceAs = YES  # can't distinguish causal from temporal "since"

# Promoted from research (see styles/Qt/Language/README.md); still opt-in

# pending a team decision on scope/policy, not a false-positive rejection.

#Qt.Language.Headings = YES              # Qt.Headings gap found during R12 testing; overlaps Microsoft.Headings -- file separately before enabling

#Qt.Language.TermConsistency = YES       # R8: proven, needs a real either: vocabulary before enabling broadly

#Qt.Language.AdmonitionHedging = YES     # R63: proven on \warning; scope to \note too before enabling

#Qt.Language.AmbiguousPronoun = YES      # R10: proven, low noise; needs wider sampling before enabling

#Qt.Language.ImperativeBrief = YES       # R5: proven; needs wider sampling before enabling

#Qt.Language.PropertySignalOpener = YES  # R18/R19: works, but makes an example opener list mandatory -- policy call

# R1 (PassiveVoice) was removed outright, not left disabled here: it used

# the same be-verb-plus-past-participle heuristic as Microsoft.Passive

# (enabled above), with a smaller irregular-verb list, so it added no

# detection Microsoft.Passive doesn't already provide.

# Qt.Structure: QDoc topic/document structure -- whether a specific QDoc

# command or page element (brief, title, anchor, table, list, image,

# version clause, module section) is present, ordered, and formatted the

# way QDoc itself expects. See styles/Qt/Structure/README.md.

Qt.Structure.QDocBrief = YES

Qt.Structure.QDocImageAlt = YES

Qt.Structure.QDocImageAltInlineCmd = YES

Qt.Structure.QDocAnchorAPIName = YES

Qt.Structure.QDocVersionClauseOrder = YES

Qt.Structure.QDocDeprecatedVersionOrder = YES

Qt.Structure.KeyboardShortcutFormat = YES

Qt.Structure.SectionLinkAntiPattern = YES

Qt.Structure.NoSpaceBeforeBrace = YES

Qt.Structure.ListItemPunctuation = YES

Qt.Structure.TableEmptyCell = YES

Qt.Structure.TableGenericHeaders = YES

Qt.Structure.AltTextFormat = YES

Qt.Structure.AltTextClassNames = YES

Qt.Structure.InlineImageAltBraces = YES

Qt.Structure.ImageAltTextContinuation = YES

Qt.Structure.ExampleTitleRepetition = YES

Qt.Structure.QMLGenericTypes = YES

# Experimental: demonstrated real false positives during testing (see

# styles/Qt/Structure/README.md) -- left disabled pending a more precise design.

#Qt.Structure.MenuPathFormat = YES    # untested false-positive rate outside the fixture

# Promoted from research (see styles/Qt/Structure/README.md); still opt-in

# pending a generated vocabulary or a working selector, not a rejection.

#Qt.Structure.ListIntroPresence = YES # R54: works via a scope: raw heuristic now -- disabled pending validation against the real doc corpus

#Qt.Structure.SaTargetVocab = YES     # R41/46/48: proof of concept only -- needs a vocabulary generated from QDoc .index files

#Qt.Structure.UIElementMarkup = YES   # R42: proof of concept only -- needs a generated UI-string list

# Qt.Mechanics: general text mechanics -- line length, spacing, repetition,

# and spelling -- checks that apply to any prose line, independent of

# wording style or QDoc structure. See styles/Qt/Mechanics/README.md.

Qt.Mechanics.Repetition = YES

Qt.Mechanics.LineLength = YES

# Qt.Mechanics.Underfilled = YES  # noisy; re-enable once tuned

Qt.Mechanics.Spacing = YES

# Extends the built-in spell checker with additional filters

Qt.Mechanics.Spelling = YES

# R58 (module landing page structure): whole-file presence checks, scoped

# to the real Qt naming convention for module index pages ({module}-index.qdoc,

# e.g. qtwidgets-index.qdoc, qtcore-index.qdoc -- verified across qtbase and

# qtdeclarative) so they run only against module landing pages, not every

# routed file. See tests/mod-index.qdoc / mod2-index.qdoc and

# styles/Qt/Structure/ModuleExamplesSection.yml et al.

[*-index.qdoc]

Qt.Structure.ModuleExamplesSection = YES

Qt.Structure.ModuleReferenceSection = YES

# R59 (example group structure): scoped to the real Qt naming convention for

# example-group definition pages ({module}-examples.qdoc, e.g.

# qtwidgets-examples.qdoc, qtdbus-examples.qdoc -- verified across qtbase,

# qtdeclarative, and qttools) so it doesn't fire on unrelated \group pages

# (cmake property/variable groups, xml-tools, richtext-processing, etc.) that

# have no business declaring \ingroup all-examples. Known residual gap: an

# individual example write-up page (documents one \example, has no \group at

# all) can also match this filename pattern and would still be misflagged --

# Vale has no way to additionally require "this file contains \group", since

# \group/\ingroup produce no distinct doc() node (see qdoc.go's qdocSkipLine)

# and RE2 has no lookaround to express the AND/negation in one rule. See

# tests/mod-examples.qdoc / mod2-examples.qdoc.

[*-examples.qdoc]

Qt.Structure.ExampleGroupIngroup = YES

Revision control

Copy as Markdown