doc: update qmlls documentation

The setup part is mainly meant for qmlls client developers, so mark it
as such. Add the download links to the standalone qmlls, in addition to
qmlls's location inside of qt. Also document that build directories can
be passed via an LSP extension, to support multiple workspaces.

Remove the parts about import paths and documentation directories, those
are handled by CMake's .qmlls.build.ini and can lead to weird behaviors
when set incorrectly.

Change-Id: I59496d20a9d02504636af6374818260c1e5f622d
Reviewed-by: Leena Miettinen <[email protected]>
Reviewed-by: Ulf Hermann <[email protected]>

1 files changed, 60 insertions, 46 deletions

diff --git a/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc b/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc
index 26b096ae38..87516e9ede 100644
--- a/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc
+++ b/src/qml/doc/src/tools/qtqml-tooling-qmlls.qdoc
@@ -90,67 +90,75 @@ by hovering over a keyword. In order to use this feature, your
 Qt kit should contain the Qt documentation and your project
 should be built with \l{QT_QML_GENERATE_QMLLS_INI} variable.
 
-\section1 Setting up the \QMLLS in Your Editor
+\section1 Setting up \QMLLS in Your Editor
 
-\note You can find the \QMLLS binary under
+This section describes how to develop the \QMLLS client or how to
+use your own \QMLLS client.
+
+You can find the \QMLLS binary under
 \c{<Qt installation folder>/bin/qmlls} in installations of Qt
-made with \QOI.
+made with \QOI. If you want your \QMLLS client to download the binary
+directly, you can download the standalone version from github via
+\l{https://github.com/TheQtCompanyRnD/qmlls-workflow/releases} or
+\l{https://qtccache.qt.io/QMLLS/LatestRelease}.
 
 \section2 Setting up the Build Directory
 
-\QMLLS needs to know the location of your build
-folder. You can pass it in the following ways:
-\list
-    \li The \c{--build-dir} command line option. In this case
-your editor should invoke \c{qmlls} as following:
+\QMLLS needs to know the location of the project build folder.
+You can pass the build folder in the following ways.
+
+\section3 AddBuildDirs LSP Extension
+
+To pass build directories via the LSP extension, send a notification
+to \QMLLS for the \c{$/addBuildDirs} method. \c{$/addBuildDirs}
+accepts one parameter of the form:
 \badcode
-<path/to/qmlls> ... --build-dir <path/to/build-directory> ...
+interface AddBuildDirsParams {
+    buildDirsToSet: UriToBuildDirs[];
+}
+\endcode
+where \c{UriToBuildDirs} contains a workspace URI and a list of build
+directories.
+The workspace URI must designate a workspace advertised to \QMLLS via
+\l{https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_workspaceFolders}{workspaceFolders}
+or
+\l{https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#workspace_didChangeWorkspaceFolders}{didChangeWorkspaceFolders}.
+The build directories are file paths, not URIs.
+\badcode
+interface UriToBuildDirs {
+    baseUri: URI;
+    buildDirs: string[];
+}
 \endcode
-    \li The \c{QMLLS_BUILD_DIRS} environment variable.
-    \li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
-\endlist
-
-\note When the build directory is specified in multiple ways, the
-command line option takes preference over the environment variable
-that takes precedence over the setting file.
 
-\section2 Setting up the import paths
+\section3 --build-dir Command Line Option
 
-\QMLLS needs to know the import paths of the Qt version that you
-are using in your project. You can pass the import paths in the
-following ways:
-\list
-    \li The \c{-I} command line option. In this case
+If you don't need to support multiple workspaces, you can pass the build
+directories via the \c{--build-dir} command line option. In this case
 your editor should invoke \c{qmlls} as following:
 \badcode
-<path/to/qmlls> ... -I /path/to/imports -I /optional/path/to/another/import ...
+<path/to/qmlls> ... --build-dir <path/to/build-directory> ...
 \endcode
-    \li The \c{QML_IMPORT_PATH} environment variable. In this case you
-        should pass the \c{-E} option to \QMLLS.
-    \li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
-\endlist
 
-\note When the import path is specified in multiple ways, the
-command line option takes preference over the environment variable
-that takes precedence over the setting file.
+The build directory will be applied to all workspaces if you use multiple
+workspaces in the same \QMLLS. The values from \c{addBuildDirsMethod}
+have higher precedence than the command line option.
 
-\section2 Setting up the documentation path
+\section3 QMLLS_BUILD_DIRS Environment Variable
 
-\QMLLS can show documentation hints when it knows the documentation
-path of the Qt version that you are using in your project. You can pass
-the documentation path in the following ways:
-\list
-    \li The \c{-d} or \c{-p} command line option. In this case
-your editor should invoke \c{qmlls} as following:
-\badcode
-<path/to/qmlls> ... -d /path/to/docs ...
-\endcode
-    \li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
-\endlist
+You can also pass the build directories via the \c{QMLLS_BUILD_DIRS}
+environment variable. The build directory will be applied to all
+workspaces if you use multiple workspaces in the same \QMLLS.
+The values from \c{--build-dir} have higher precedence than the
+environment variable.
 
-\note When the documentation path is specified in multiple ways, the
-command line option takes preference over the environment variable
-that takes precedence over the setting file.
+\section3 \c{.qmlls.ini} Settings File
+
+If you can't pass the build directories using one of the previous options,
+you could try passing build directories to \QMLLS via a configuration file.
+See also \l{Configuration File}.
+The values from the settings file have lower precedence than
+\c{--build-dir}, \c{QMLLS_BUILD_DIRS}, and \c{addBuildDirsMethod}.
 
 \section2 Configuring Automatic CMake Builds
 
@@ -166,7 +174,8 @@ your editor should invoke \c{qmlls} as follows:
 \endcode
     \li The \c{QMLLS_NO_CMAKE_CALLS} environment variable.
     \li The \c{.qmlls.ini} settings file, see \l {Configuration File}.
-    \li The \l{QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS} CMake variable.
+    \li The \l{QT_QML_GENERATE_QMLLS_INI_NO_CMAKE_CALLS} CMake variable
+if \l{QT_QML_GENERATE_QMLLS_INI} is enabled.
 \endlist
 
 To control the number of jobs used by CMake, use
@@ -212,9 +221,14 @@ importPaths=<path/to/imports>      # not required in Qt 6.10 and later
 
 To use the configuration file to disable the automatic CMake rebuild
 functionality, set \c{no-cmake-calls} to \c{true}.
+
 To control the number of jobs used by automatic CMake rebuilds, set the
 CMakeJobs value.
 
+To support clients that can't pass the build directory to \QMLLS, as
+described in \l{Setting up the Build Directory}, set the buildDir value
+or let CMake generate the .qmlls.ini via \l {QT_QML_GENERATE_QMLLS_INI}.
+
 \note \QMLLS can create default configuration files
 using the \c{--write-defaults} option. This will overwrite an
 already existing .qmlls.ini file in the current directory.