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. 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 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
- */