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

/*!
    \page creator-language-servers.html
    \previouspage creator-reference.html

    \ingroup creator-reference-editors

    \title Language Servers

    \brief Get code completion, highlighting of the symbol under cursor, and
    jumping to the symbol definition in the editor for other programming
    languages besides C++, as well as diagnostics.

    For several programming languages, a \e {language server} offers
    information about the code to IDEs as long as they support
    communication via the \l{Language Server Protocol}
    {language server protocol (LSP)}. The IDE can then offer the
    following services:

    \list
        \li \l{Complete code}{Code completion}
        \li Sending document formatting requests to the language server to
            automatically format documents using the settings specified in
            \preferences > \uicontrol {Text Editor} > \uicontrol Behavior
        \li Highlighting the symbol under cursor
        \li \l{View function tooltips}{Viewing function tooltips}
        \li \l{Semantic Highlighting}{Semantic highlighting}, as defined in
            \l{https://github.com/microsoft/vscode-languageserver-node/pull/367}
            {Proposal of the semantic highlighting protocol extension}
        \li Navigating in the code by using the \l{Navigate with locator}
            {locator} or \l{Move to symbol definition or declaration}
            {moving to the symbol definition}
        \li Inspecting code by viewing the document outline in the
            \l{Outline} view or in the \uicontrol Symbols list on the
            \l{Edit Mode}{editor toolbar}
        \li \l{Call Hierarchy}{Viewing the callers and callees of a function}
        \li \l{Type Hierarchy}{Viewing the base classes and derived classes of a class}
        \li \l{Find references to a symbol}{Finding references to symbols}
        \li \l{Rename symbols}{Renaming the symbol under the cursor}
        \li Code actions
        \li Displaying diagnostics from the language server as tooltips. You can
            also select a code range to display diagnostics for.
    \endlist

    By providing a client for the language server protocol, \QC can support
    the above features for several other programming languages besides C++.
    However, the client does not support language servers that require special
    handling.

    \section1 Adding MIME Types for Language Servers

    \QC uses the \l{https://www.iana.org/assignments/media-types/media-types.xhtml}
    {MIME type} of the file to determine which language server to request
    information from when you open a file for editing. Add new MIME types or
    file patterns to match language servers. If you do not set at least one MIME
    type or file pattern, no files will be sent to the language server. This is
    done to avoid unnecessary traffic and inaccurate information, as files are
    only sent to the language server if they are known to be handled by it. For
    more information about how \QC uses MIME types, see
    \l {Edit MIME types}.

    \section1 Adding Language Servers

    \QC adds a \l{Configure Python language servers}{Python language server} by
    default.

    Also, it offers to install language servers for JSON and YAML files
    when you open them in the editor if it can find the
    \l{https://nodejs.org/en/learn/getting-started/an-introduction-to-the-npm-package-manager}
    {NPM} package manager on the computer.

    \image {qtcreator-language-server-json.webp} {Prompt to install JSON language server}

    \l{Add a Java language server} for  \l{Developing for Android}
    {Android development}. For other languages,
    \l{Add generic language servers}{add generic stdIO language servers}.

    To add language servers, go to \preferences > \uicontrol {Language Client}
    and select \uicontrol Add.

    \image {qtcreator-preferences-language-client-qmlls.webp} {General tab in Language Client preferences}

    To enable a language server, select the checkbox next to the language
    server name and set server preferences.

    To remove language servers from the list, select \uicontrol Delete.

    \section1 Updating Python Language Server

    \QC offers to update the Python language server when you open a Python
    file in the editor.

    \image {qtcreator-python-update-language-server.webp} {Message about updating Python Language Server}

    To update the language server, select \uicontrol Update. To save your choice,
    select \uicontrol {Always Update}.

    To skip updating and hide the message for future updates, select
    \uicontrol Never.

    \section1 Supported Locator Filters

    The locator enables you to browse not only files, but any items defined by
    \e {locator filters}. The language client plugin supports the following
    locator filters:

    \list
            \li Locating symbols in the current project (\c {:})
            \li Locating symbols in the current document (\c {.})
            \li Locating class (\c {c}), enum, and function (\c {m})
                definitions in your project
    \endlist

    \section1 Reporting Issues

    The language server client has been mostly tested with Python and C++.
    If problems arise when you try them or some other language, please select
    \uicontrol Help > \uicontrol {Report Bug} to report them in the
    \l{https://bugreports.qt.io/}{Qt Project Bug Tracker}. The reports
    should include \QC console output with the environment
    variable \c {QT_LOGGING_RULES=qtc.languageclient.*=true} set.

    \sa {Manage Language Servers}{How To: Manage Language Servers}, {Behavior}
*/

/*!
    \page creator-how-to-add-generic-language-servers.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-lsp

    \title Add generic language servers

    To add a generic StdIO language server:

    \list 1
        \li Go to \preferences > \uicontrol {Language Client} >
            \uicontrol Add > \uicontrol {Generic StdIO Language Server}
            to add a generic language server.
            \image {qtcreator-language-server-generic-stdio.png} {Generic StdIO Language Server in the General tab in Language Client preferences}
        \li In the \uicontrol Name field, enter a name for the language server.
            Select \inlineimage {icons/replace.png} {Variables}
            (\uicontrol {Variables}) to use a variable for the server
            name. For more information, see \l{Use Qt Creator variables}.
        \li In \uicontrol {Language}, select
            \uicontrol {Set MIME Types} to select the MIME types of the files to
            send to the language server. In the field below, you can enter file
            patterns to extend the MIME types, separated by semicolons.
        \li In \uicontrol {Startup behavior}, select whether the
            language server is started when \QC starts or when a project or file
            with a matching MIME type is opened. \l{View output}
            {General Messages} displays information about the connection to the
            language server.
        \li In \uicontrol {Initialization options}, you can add
            language server specific JSON attributes to pass to an \c initialize
            request.
        \li In \uicontrol Executable, enter the path to the language
            server executable.
        \li In \uicontrol Arguments, enter any required command-line
            arguments. Select \uicontrol Variables to use variables as
            arguments.
    \endlist

    \sa {Manage Language Servers}{How To: Manage Language Servers},
    {Language Servers}
*/

/*!
    \page creator-how-to-add-java-language-servers.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-lsp

    \title Add a Java language server

    To add a Java language server for developing Android applications:

    \list 1
        \li Go to \preferences > \uicontrol {Language Client} >
            \uicontrol Add > \uicontrol {Java Language Server} to add
            a Java language server.
            \image {qtcreator-language-client-options-java.png} {Java language server in the General tab in Language Client preferences}
        \li In \uicontrol Name, enter a name for the language server.
            Select \inlineimage {icons/replace.png} {Variables}
            (\uicontrol {Variables}) to use a variable for the server
            name.
        \li In \uicontrol Java, enter the path to the Java executable.
        \li In \uicontrol {Java Language Server}, enter the path to
            the Java language server \c .jar file. You can download the Java
            language server from \l{https://download.eclipse.org/jdtls/milestones/}
            {Eclipse Downloads}.
    \endlist

    \sa {Manage Language Servers}{How To: Manage Language Servers},
    {Use Qt Creator variables}, {Language Servers}
*/

/*!
    \page creator-how-to-configure-python-language-servers.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-lsp

    \title Configure Python language servers

    To set preferences for Python language servers:

    \list 1
        \li Go to \preferences> \uicontrol Python >
            \uicontrol {Language Server Configuration} to
            select the Python language server plugins to use.
            \image {qtcreator-python-plugins.png} {Language Server Configuration in the Python preferences}
        \li Select \uicontrol Advanced to configure the plugins.
            \image {qtcreator-python-advanced.png} {Python language server plugin configuration}
    \endlist

    For a complete list of configuration options, see
    \l{https://github.com/python-lsp/python-lsp-server/blob/develop/CONFIGURATION.md}
    {Python Language Server Configuration}.

    To disable the Python language server, clear
    \uicontrol {Use Python Language Server}.

    \sa {Manage Language Servers}{How To: Manage Language Servers},
    {Develop Qt for Python applications}, {Language Servers}
*/

/*!
    \page creator-how-to-use-qml-language-server.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-lsp

    \title Configure \QMLLS

    Since Qt 6.4, \QMLLS offers code completion and issues warnings for QML.

    To set preferences for \QMLLS, go to \preferences >
    \uicontrol {Language Client} > \uicontrol General and
    select \uicontrol {\QMLLS}.

    \image {qtcreator-preferences-language-client-qmlls.webp} {General tab in Language Client preferences}

    \section1 Turn off \QMLLS for all projects

    To globally turn off \QMLLS, clear the \uicontrol {\QMLLS} checkbox.

    For more information about how to turn on and off language servers for a
    particular project, see \l{Configure language servers for projects}.

    \section1 Use advanced features

    By default, \QMLLS issues warning messages and provides code completion,
    while the embedded code model handles advanced features, such as renaming
    symbols and finding usages.

    To disable the embedded code model and use \QMLLS for everything, select
    \uicontrol {Use advanced features}.

    \section1 Select \QMLLS version

    To use \QMLLS shipped with the Qt version in your current \l{Kits}{kit},
    select \uicontrol {Use qmlls from project Qt kit}. This is the default
    option.

    To always use \QMLLS of the highest registered Qt version, select
    \uicontrol {Use qmlls from latest Qt kit}.

    To use older \QMLLS versions, select
    \uicontrol{Allow versions below Qt 6.8}.

    To use a specific \QMLLS version, set the path to the executable in
    \uicontrol {Use custom qmlls executable}. To download the latest
    \QMLLS version, select \uicontrol {Download latest standalone qmlls}.

    \section1 Automatically configure new CMake projects

    To automatically configure new CMake projects, select
    \uicontrol {Create .qmlls.ini files for new projects}.

    \sa {Manage Language Servers}{How To: Manage Language Servers},
    {Enabling and Disabling Messages}, {CMake Build Configuration}, {Kits},
    {Language Servers}
*/

/*!
    \page creator-how-to-inspect-language-clients.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-lsp

    \title Inspect language clients

    \QC sends messages (\e requests) to a \l{Language Servers}{language server} and
    receives responses that have the requested information if the language server is
    capable of handling the requests. To inspect the communication between \QC
    and language servers and to view server capabilities, select \uicontrol Tools
    > \uicontrol {Debug \QC} > \uicontrol {Inspect Language Clients}.

    \image qtcreator-language-client-inspector-log.webp {Language Client Inspector dialog}

    Select a running language server in \uicontrol {Language Server}. The
    information displayed depends on the language server.

    For a generic language server, the value of the \uicontrol {Startup behavior}
    field in the \l{Add generic language servers}{language server preferences}
    determines when the server is started. To restart language servers, select
    \inlineimage {icons/languageclient.png} {Language Client menu} on the
    \l{Edit Mode} {editor toolbar}, and then select \uicontrol {Restart}.

    \uicontrol Log displays additional information about the selected log entry.
    You can see the \uicontrol {Content length} and \uicontrol {MIME type} of
    a \uicontrol {Client Message} and \uicontrol {Server Message}, as well as
    inspect the data sent between \QC and the language server.

    To remove old entries, select \uicontrol Clear.

    \section1 Check language server capabilities

    In \uicontrol Capabilities, you can check whether a language server is
    capable of a specific task. You cannot modify the server capabilities
    in this dialog.

    You can view the \uicontrol Name, \uicontrol Value, and \uicontrol Type
    of the capability.

    \image {qtcreator-language-client-inspector-capabilities.webp} {Capabilities tab in the Language Client Inspector dialog}

    For some language servers, \uicontrol {Dynamic Capabilities} lists the
    \uicontrol Methods and \uicontrol Options available.

    \section1 Inspect memory usage

    For a clangd server, you can inspect the total amount of memory used by a
    particular component in \uicontrol {Memory Usage}.

    \image {qtcreator-language-client-inspector-memory-usage.webp} {Memory Usage tab in the Language Client Inspector dialog}

    \sa {Manage Language Servers}{How To: Manage Language Servers},
    {Language Servers}
*/

/*!
    \page creator-how-to-configure-lsp-workspace.html
    \previouspage creator-how-tos.html

    \ingroup creator-how-to-lsp
    \ingroup creator-how-to-projects-configure

    \title Configure language servers for projects

    To configure language servers for the current project, go to
    \uicontrol Projects > \uicontrol {Project Settings} >
    \uicontrol {Language Server}.

    \image {qtcreator-projects-settings-language-server.webp} {Language Server settings for a project}

    To add language servers and change their preferences, select
    \uicontrol {Global settings}.

    \section1 Turn on and off language servers

    To turn on and off language servers, select \uicontrol Enabled or
    \uicontrol Disabled in \uicontrol {Project Specific Language Servers}.

    \section1 Configure language server workspace

    The language client sends the contents of the
    \uicontrol {Workspace Configuration} field as a JSON file to all language
    servers that have files open that belong to the project. The contents of the
    JSON file must be valid JSON. The available settings depend on the language
    server.

    In \uicontrol {Workspace Configuration}, specify language server settings
    using valid JSON format.

    \sa {Manage Language Servers}{How To: Manage Language Servers},
    {Language Servers}, {Configuring Projects}
*/
