Revision control
// Copyright (C) 2026 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only
// Tests that Vale does not lint content inside QDoc code blocks.
// Prose outside code blocks SHOULD warn; content inside SHOULD NOT.
// SHOULD WARN: passive voice in prose around \code block
/*!
\fn void QFile::open()
\brief Opens the file for reading and writing.
The file is opened by calling this function.
Call this function before reading any data:
\code
QFile file("example.txt");
// We recommend utilizing this pattern in order to open files
if (file.open(QIODevice::ReadOnly)) {
QByteArray data = file.readAll();
}
\endcode
The data is returned as a QByteArray on \macos and \MACRO1.
*/
// SHOULD WARN: passive voice in prose around \qml block
/*!
\qmltype FileDialog
\brief Provides a dialog for selecting files.
The dialog is shown by calling open():
\qml
FileDialog {
// We recommend utilizing this pattern in order to show dialogs
title: "Please choose a file"
onAccepted: {
console.log("You chose: " + fileDialog.selectedFile)
}
}
\endqml
The selected file is returned via the selectedFile property.
*/
// SHOULD WARN: wordiness in prose around \badcode block
/*!
\fn void QTimer::start()
\brief Starts the timer.
Prior to calling start(), set the interval in milliseconds.
Utilize stop() in order to cancel the timer.
The following code is incorrect and should not be used:
\badcode
// We recommend utilizing this pattern in order to start timers
QTimer timer;
timer.start(-1);
\endcode
*/
- // SHOULD WARN: prose in a \qmltype block is linted — \qmltype must not
- // start the (?s)\\qml\s.*?\\endqml region; only \qml followed by
- // whitespace opens a code block. (Microsoft.Wordiness, Microsoft.We,
+ // SHOULD WARN: prose in a \qmltype block is linted. Only a \qml code
+ // block is skipped; \qmltype is a topic command and its prose is
+ // linted normally. (Microsoft.Wordiness, Microsoft.We,
// Microsoft.Passive)
/*!
\qmltype FixtureSlider
\inqmlmodule QtQuick.Controls
\brief Selects a value by sliding a handle.
In order to react to changes, we recommend the handler.
The value is changed by the user.
*/
// SHOULD NOT WARN: \qml block contents are code, not prose
/*!
\qmltype FixtureSlider
\inqmlmodule QtQuick.Controls
\brief Selects a value by sliding a handle.
\qml
Slider { value: 0.5 } // In order to test, we utilize this
\endqml
*/
- // SHOULD WARN: prose after \codeline is linted — \codeline must not
- // start the (?s)\\code\s.*?\\endcode region; only \code followed by
- // whitespace opens a code block. (Microsoft.Wordiness, Microsoft.We,
+ // SHOULD WARN: prose after \codeline is linted. \codeline is a
+ // single-line command, not a code-block opener, so the prose that
+ // follows it is linted normally. (Microsoft.Wordiness, Microsoft.We,
// Microsoft.Passive)
/*!
\fn void QFont::setFamily(const QString &family)
\brief Sets the font family.
\codeline qfont.setFamily("Arial");
In order to set a default, we recommend this approach.
The font is changed when the value is updated by the system.
\code
// We recommend utilizing this pattern in order to load fonts
QFont font("Arial");
font.setPointSize(12);
\endcode
*/