// Copyright (C) 2024 The Qt Company Ltd.
// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only

/*!
    \page creator-checking-code-syntax.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-analyze

    \title Check code syntax

    As you write code, \QC checks code syntax. When \QC spots a syntax error in
    your code, it underlines it, displays an icon, and shows error details when
    you move the mouse pointer over the error or the icon. To apply an available
    fix, select \inlineimage {icons/refactormarker.png} {Light bulb icon}.

    Similarly, when you are working on an instance of a JavaScript object
    notation (JSON) entity, \QC underlines errors in the JSON data structure.

    \section1 Examples of C++ code errors

    \QC annotates an error because a semicolon is missing at the end of the line:

    \image {qtcreator-syntaxerror.png} {Syntax error in the Edit mode}

    \QC issues a warning because the variable is not used:

    \image {qtcreator-semanticerror.png} {Semantic error in the Edit mode}

    A Qt class name has a typo:

    \image {qtcreator-typo-clang.png} {Annotation tooltip in the Edit mode}

    \section1 Check QML or JavaScript syntax

    When writing QML or JavaScript code, the annotations may have error codes.

    If you turn on \QMLLS for a project, it uses \c {qmllint} to check QML and
    JavaScript code. For more information, see \l {qmllint Reference}.

    If you turn off \QMLLS, \QC uses a static analyzer. For more information,
    see \l{JavaScript and QML Error Codes}.

    \image {qml-syntax-check.png} {Selecting checks for the static analyzer}

    \section1 Manage messages

    Use the icons in the tooltip popup to copy the error or
    warning message to the clipboard, to hide messages of a particular type,
    or to change the diagnostics settings.

    To modify the colors used for underlining errors and warnings:

    \list 1
        \li Go to \preferences > \uicontrol {Text Editor} >
            \uicontrol {Font & Colors} > \uicontrol Copy
        \li Select new colors for \uicontrol Error and \uicontrol Warning.
    \endlist

    \section1 Set line annotation positions

    To specify the position where the annotations are displayed, go to
    \preferences > \uicontrol {Text Editor} >
    \uicontrol Display > \uicontrol {Line Annotations}, and then select
    whether to display the annotations directly next to the code, aligned
    to the right of the code, or in the right margin. Showing annotations
    between lines can be useful if there is usually not enough space to
    display annotations next to the text.

    \image {qtcreator-preferences-text-editor-display.webp} {Display tab Text Editor preferences}

    If you hide the annotations, you can move the mouse pointer over an icon to
    view them.

    \sa {Analyze}{How to: Analyze}, {Analyzers}, {Analyzing code},
    {JavaScript and QML Checks}
*/

/*!
    \page creator-reference-js-and-qml-error-codes.html
    \previouspage creator-reference.html

    \ingroup creator-reference-analyzer

    \title JavaScript and QML Checks

    \summary {Run static checks on the QML and JavaScript code in your project to
    find common problems.}

    To run static checks, go to \uicontrol Tools > \uicontrol {QML/JS} >
    \uicontrol {Run Checks} or select \key {Ctrl+Shift+C}.

    View the results in the \uicontrol QML and \uicontrol {QML Analysis}
    filters in \l Issues.

    \note If you turn on \QMLLS for a project, it uses \l {qmllint Reference}
    {qmllint} to check QML and JavaScript code and to generate warnings, so the
    error codes and messages differ from those in
    \l{JavaScript and QML Error Codes}.

    \section1 Enabling and Disabling Messages

    To enable and disable QML and JavaScript messages of the static analyzer:

    \list 1
        \li Go to \preferences > \uicontrol {Qt Quick} >
            \uicontrol {QML/JS Editing}.
        \li Select \uicontrol {Use customized static analyzer}.
            \image {qtcreator-preferences-qtquick-qmljs-editing.webp} {QML/JS Editing tab in Qt Quick preferences}
        \li In \uicontrol Enabled, select the messages that you want to see.
        \li To show particular messages only for Qt Quick UI files, select them in
            \uicontrol {Only for Qt Quick UI}. You cannot enable messages just for non-Qt Quick UI
            files.
    \endlist

    \section1 JavaScript and QML Error Codes

    Many of the error messages are similar to the ones in Douglas Crockford's
    \l{http://www.jslint.com}{JSLint} tool. For more information about JSLint
    errors, see \l{https://github.com/jamesallardice/jslint-error-explanations}
    {JSLint Error Explanations}.

    \table
    \header
        \li Id
        \li Severity
        \li Message
        \li Description

    \row
        \li M1
        \li Error
        \li Invalid value for enum
        \li

    \row
        \li M2
        \li Error
        \li Enum value must be a string or a number
        \li

    \row
        \li M3
        \li Error
        \li Number value expected
        \li

    \row
        \li M4
        \li Error
        \li Boolean value expected
        \li

    \row
        \li M5
        \li Error
        \li String value expected
        \li

    \row
        \li M6
        \li Error
        \li Invalid URL
        \li

    \row
        \li M7
        \li Warning
        \li File or directory does not exist
        \li

    \row
        \li M8
        \li Error
        \li Invalid color
        \li

    \row
        \li M9
        \li Error
        \li Anchor line expected
        \li

    \row
        \li M10
        \li Error
        \li Duplicate property binding
        \li For more information, see \e {Duplicate key '{a}'} in
            \e {JSLint Error Explanations}.

    \row
        \li M11
        \li Error
        \li Id expected
        \li For more information, see
            \e {Expected an identifier and instead saw '{a}' (a reserved word)}
            in \e {JSLint Error Explanations}.

    \row
        \li M14
        \li Error
        \li Invalid id
        \li For more information, see
            \e {Expected an identifier and instead saw '{a}' (a reserved word)}.

    \row
        \li M15
        \li Error
        \li Duplicate id
        \li Ids in a file must be unique.
            For more information, see \e {Duplicate key '{a}'}.

    \row
        \li M16
        \li Error
        \li Invalid property name \c name
        \li

    \row
        \li M17
        \li Error
        \li \c Name does not have members
        \li

    \row
        \li M18
        \li Error
        \li \c Field is not a member of \c object
        \li

    \row
        \li M19
        \li Warning
        \li Assignment in condition
        \li It could be a typing error. If it is intentional, wrap the
            assignment in parentheses.

    \row
        \li M20
        \li Warning
        \li Unterminated non-empty case block
        \li Case blocks should either be empty or end in a flow control
            statement such as \c break, \c return or \c continue.
            Alternatively you can indicate intentional fall through by ending
            with a \c {// fall through} comment.

    \row
        \li M23
        \li Warning
        \li Do not use \c eval
        \li For more information, see \e {eval is evil} in
            \e {JSLint Error Explanations}.

    \row
        \li M28
        \li Warning
        \li Unreachable
        \li Indicates that the underlined statement will never be executed.

    \row
        \li M29
        \li Warning
        \li Do not use \c with
        \li For more information, see \e {Unexpected 'with'} in
            \e {JSLint Error Explanations}.

    \row
        \li M30
        \li Warning
        \li Do not use comma expressions
        \li

    \row
        \li M31
        \li Warning
        \li Unnecessary message suppression
        \li

    \row
        \li M103
        \li Warning
        \li \c Name is already a formal parameter
        \li

    \row
        \li M104
        \li Warning
        \li \c Name is already a function
        \li

    \row
        \li M105
        \li Warning
        \li Var \c name is used before its declaration
        \li

    \row
        \li M106
        \li Warning
        \li \c Name already is a var
        \li

    \row
        \li M107
        \li Warning
        \li \c Name is declared more than once
        \li Variables declared in a function are always visible everywhere in
            the function, even when declared in nested blocks or \c for
            statement conditions. Redeclaring a variable has no effect.

    \row
        \li M108
        \li Warning
        \li Function \c name is used before its declaration
        \li For more information, see \e {{a} was used before it was defined} in
            \e {JSLint Error Explanations}.

    \row
        \li M109
        \li Warning
        \li Do not use \c Boolean as a constructor
        \li For more information, see \e {Do not use {a} as a constructor} in
            \e {JSLint Error Explanations}.

    \row
        \li M110
        \li Warning
        \li Do not use \c String as a constructor
        \li For more information, see \e {Do not use {a} as a constructor}.

    \row
        \li M111
        \li Warning
        \li Do not use \c Object as a constructor
        \li For more information, see \e {Do not use {a} as a constructor}.

    \row
        \li M112
        \li Warning
        \li Do not use \c Array as a constructor
        \li For more information, see \e {Do not use {a} as a constructor}.

    \row
        \li M113
        \li Warning
        \li Do not use \c Function as a constructor
        \li For more information, see \e {Do not use {a} as a constructor}.

    \row
        \li M114
        \li Hint
        \li The \c function keyword and the opening parenthesis should be
            separated by a single space
        \li For more information, see
            \e {Expected exactly one space between {a} and {b}} in
            \e {JSLint Error Explanations}.

    \row
        \li M115
        \li Warning
        \li Do not use stand-alone blocks
        \li Blocks do not affect variable scoping. Thus blocks that are not
            associated to \c if, \c while, etc. have no effect and should be
            avoided.

    \row
        \li M116
        \li Warning
        \li Do not use void expressions
        \li

    \row
        \li M117
        \li Warning
        \li Confusing pluses
        \li For more information, see \e {Confusing pluses} in
            \e {JSLint Error Explanations}.

    \row
        \li M119
        \li Warning
        \li Confusing minuses
        \li For more information, see \e {Confusing minuses} in
            \e {JSLint Error Explanations}.

    \row
        \li M121
        \li Hint
        \li Declare all function vars on a single line
        \li

    \row
        \li M123
        \li Hint
        \li Unnecessary parentheses
        \li

    \target m126
    \row
        \li M126
        \li Warning
        \li \c == and \c != may perform type coercion, use \c === or \c !== to
            avoid it
        \li The non-strict equality comparison is allowed to convert its
            arguments to a common type. That can lead to unexpected results such
            as \c {' \t\r\n' == 0} being true. Use the strict equality operators
            \c === and \c !== and be explicit about conversions you require.

    \row
        \li M127
        \li Warning
        \li Expression statements should be assignments, calls or delete
            expressions only
        \li

    \row
        \li M128
        \li Error
        \li A state cannot have the specified child item
        \li

    \row
        \li M129
        \li Error
        \li Type cannot be instantiated recursively
        \li

    \row
        \li M201
        \li Hint
        \li Place var declarations at the start of a function
        \li For more information, see
            \e {Move 'var' declarations to the top of the function} in
            \e {JSLint Error Explanations}.

    \row
        \li M202
        \li Hint
        \li Use only one statement per line
        \li

    \row
        \li M203
        \li Warning
        \li Imperative code is not supported in \QMLD
        \li

    \row
        \li M204
        \li Warning
        \li This QML type is not supported in \QMLD
        \li
    \row
        \li M205
        \li Warning
        \li Reference to parent QML type cannot be resolved correctly by \QMLD
        \li

    \row
        \li M206
        \li Warning
        \li This visual property binding cannot be evaluated in the local
            context and might not show up in \QMLD as expected
        \li

    \row
        \li M207
        \li Warning
        \li \QMLD only supports states in the root QML type
        \li

    \row
        \li M208
        \li Error
        \li This id might be ambiguous and is not supported in \QMLD
        \li

    \row
        \li M209
        \li Error
        \li This type (type name) is not supported as a root element in
            \QMLD
        \li

    \row
        \li M220
        \li Error
        \li This type (type name) is not supported as a root element of a
            UI file (\c .ui.qml)
        \li For more information about supported QML types, see \l{UI files}.

    \row
        \li M221
        \li Error
        \li This type (type name) is not supported in a UI file (\c .ui.qml)
        \li For more information about supported QML types, see \l{UI files}.

    \row
        \li M222
        \li Error
        \li Functions are not supported in a UI file (\c .ui.qml)
        \li For a list of supported JavaScript functions, see
            \l{Supported Methods}.

    \row
        \li M223
        \li Error
        \li JavaScript blocks are not supported in a UI file (\c .ui.qml)
        \li For more information about supported features, see \l{UI files}.

    \row
        \li M224
        \li Error
        \li Behavior type is not supported in a UI file (\c .ui.qml)
        \li For more information about supported QML types, see \l{UI files}.

    \row
        \li M225
        \li Error
        \li States are only supported in the root item in a UI file (\c .ui.qml)
        \li For more information about supported features, see \l{UI files}.

    \row
        \li M226
        \li Error
        \li Referencing the parent of the root item is not supported in a
            UI file (\c .ui.qml)
        \li For more information about supported features, see \l{UI files}.

    \row
        \li M227
        \li Error
        \li Do not mix translation functions in a UI file (\c .ui.qml)
        \li Even though several different translation functions, such as
            \c qsTr and \c qsTrId are supported, you should pick one and
            use it consistently within a UI file. For more information,
            see \l{Qt QML Methods}.

    \row
        \li M300
        \li Error
        \li Unknown component
        \li

    \row
        \li M301
        \li Error
        \li Could not resolve the prototype \c name of \c object
        \li

    \row
        \li M302
        \li Error
        \li Could not resolve the prototype \c name
        \li

    \row
        \li M303
        \li Error
        \li Prototype cycle, the last non-repeated component is \c name
        \li

    \row
        \li M304
        \li Error
        \li Invalid property type \c name
        \li
    \row
        \li M305
        \li Warning
        \li \c == and \c != perform type coercion, use \c === or \c !== to
            avoid it
        \li See \l{m126}{M126}.
    \row
        \li M306
        \li Warning
        \li Calls of functions that start with an uppercase letter should use
            \c new
        \li By convention, functions that start with an uppercase letter
            are constructor functions that should only be used with \c new.

    \row
        \li M307
        \li Warning
        \li Use \c new only with functions that start with an uppercase letter
        \li For more information, see \e {Do not use {a} as a constructor} in
            \e {JSLint Error Explanations}.

    \row
        \li M308
        \li Warning
        \li Do not use \c Number as a constructor
        \li For more information, see \e {Do not use {a} as a constructor}.

    \row
        \li M309
        \li Hint
        \li Use spaces around binary operators
        \li

    \row
        \li M310
        \li Warning
        \li Unintentional empty block, use ({}) for empty object literal
        \li

    \row
        \li M311
        \li Hint
        \li Use \c type instead of \c var or \c variant to improve performance
        \li

    \row
        \li M312
        \li Error
        \li Missing property \c number
        \li

    \row
        \li M313
        \li Error
        \li Object value expected
        \li

    \row
        \li M314
        \li Error
        \li Array value expected
        \li

    \row
        \li M315
        \li Error
        \li \c Value value expected
        \li

    \row
        \li M316
        \li Error
        \li Maximum number value is \c number
        \li

    \row
        \li M317
        \li Error
        \li Minimum number value is \c number
        \li

    \row
        \li M318
        \li Error
        \li Maximum number value is exclusive
        \li

    \row
        \li M319
        \li Error
        \li Minimum number value is exclusive
        \li

    \row
        \li M320
        \li Error
        \li String value does not match required pattern
        \li

    \row
        \li M321
        \li Error
        \li Minimum string value length is \c number
        \li

    \row
        \li M322
        \li Error
        \li Maximum string value length is \c number
        \li

    \row
        \li M323
        \li Error
        \li \c Number elements expected in array value
        \li For more information, see
            \e {The array literal notation [] is preferable} in
            \e {JSLint Error Explanations}.

    \row
        \li M324
        \li Error
        \li Hit maximum recursion limit visiting AST, the code model will be unreliable
            and most likely invalid
        \li

    \row
        \li M326
        \li Error
        \li Components are only allowed to have a single child element
        \li For more information, see \l [QML] {Component}.

    \row
        \li M327
        \li Warning
        \li Components require a child element
        \li For more information, see \l [QML] {Component}.

    \row
        \li M400
        \li Warning
        \li Duplicate import
        \li An import statement has been added twice. For more information,
            see \l{Import Statements}.

    \row
        \li M401
        \li Error
        \li Do not reference the root item as alias
        \li The alias property cannot reference the root component directly.
            Create an instance of the component instead.

    \row
        \li M402
        \li Warning
        \li Avoid referencing the root item in a hierarchy
        \li The alias property cannot reference the root component in a
            hierarchy. Create an instance of the component instead.

    \row
        \li M403
        \li Error
        \li A when condition cannot contain an object
        \li Set the \c when condition to an expression that evaluates to \c true
            when the condition is met.

    \endtable

    \section1 Resetting the Code Model

    If you see the following error messages after you add a new QML module,
    try building the project and then resetting the code model:

    \list
        \li QML module not found.
        \li Unknown Component (M300).
    \endlist

    To see an error message, move the mouse pointer over code that
    \QC underlines in the code editor or when you open a QML file in \QMLD.

    To reset the code model, select \uicontrol Tools > \uicontrol {QML/JS} >
    \uicontrol {Reset Code Model}.

    \sa {Check code syntax}, {Analyzing code}, {Using QML modules with plugins}
*/

/*!
    \page creator-how-to-autoformat-qml-js.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-edit

    \title Automatically format QML/JS files

    To automatically format QML/JS files upon saving, go to \preferences >
    \uicontrol {Qt Quick} > \uicontrol {QML/JS Editing} and select
    \uicontrol {Enable auto format on file save}.

    \image {qtcreator-qml-js-editing.webp} {QML/JS Editing tab in Qt Quick preferences}

    To temporarily disable this setting while saving a file  go to
    \uicontrol File and select \uicontrol {Save Without Formatting}.

    To only format files that belong to the current project, select
    \uicontrol {Restrict to files contained in the current project}.

    \sa {Check code syntax}, {Specify Qt Quick code style}
*/
