gribozavr updated this revision to Diff 188534.
gribozavr added a comment.
Separated user and developer documentation
Repository:
rG LLVM Github Monorepo
CHANGES SINCE LAST ACTION
https://reviews.llvm.org/D58710/new/
https://reviews.llvm.org/D58710
Files:
clang-tools-extra/docs/_static/clang-tools-extra-styles.css
clang-tools-extra/docs/_templates/layout.html
clang-tools-extra/docs/clangd/ApplyClangTidyFixInVSCode.gif
clang-tools-extra/docs/clangd/ApplyFixInVSCode.gif
clang-tools-extra/docs/clangd/CodeCompletionInEmacsCompanyMode.png
clang-tools-extra/docs/clangd/CodeCompletionInSublimeText.png
clang-tools-extra/docs/clangd/CodeCompletionInVSCode.png
clang-tools-extra/docs/clangd/CodeCompletionInYCM.png
clang-tools-extra/docs/clangd/CodeCompletionInsertsNamespaceQualifiersInVSCode.gif
clang-tools-extra/docs/clangd/Compiling.rst
clang-tools-extra/docs/clangd/Contributing.rst
clang-tools-extra/docs/clangd/DeveloperDocumentation.rst
clang-tools-extra/docs/clangd/DiagnosticsInEmacsEglot.png
clang-tools-extra/docs/clangd/ErrorsInVSCode.png
clang-tools-extra/docs/clangd/Extensions.rst
clang-tools-extra/docs/clangd/Features.rst
clang-tools-extra/docs/clangd/FindAllReferencesInVSCode.gif
clang-tools-extra/docs/clangd/FormatSelectionInVSCode.gif
clang-tools-extra/docs/clangd/GoToDefinitionInVSCode.gif
clang-tools-extra/docs/clangd/Installation.rst
clang-tools-extra/docs/clangd/NavigationWithBreadcrumbsInVSCode.gif
clang-tools-extra/docs/clangd/OutlineInVSCode.png
clang-tools-extra/docs/clangd/SignatureHelpInVSCode.gif
clang-tools-extra/docs/clangd/index.rst
clang-tools-extra/docs/conf.py
clang-tools-extra/docs/index.rst
Index: clang-tools-extra/docs/index.rst
===================================================================
--- clang-tools-extra/docs/index.rst
+++ clang-tools-extra/docs/index.rst
@@ -21,6 +21,7 @@
pp-trace
clang-rename
clangd/index
+ clangd/DeveloperDocumentation
clang-doc
Index: clang-tools-extra/docs/conf.py
===================================================================
--- clang-tools-extra/docs/conf.py
+++ clang-tools-extra/docs/conf.py
@@ -121,7 +121,7 @@
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = []
+html_static_path = ['_static']
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
Index: clang-tools-extra/docs/clangd/index.rst
===================================================================
--- clang-tools-extra/docs/clangd/index.rst
+++ clang-tools-extra/docs/clangd/index.rst
@@ -1,180 +1,27 @@
-============
-Clangd
-============
-
-.. contents::
+======
+clangd
+======
.. toctree::
:maxdepth: 1
-:program:`Clangd` is an implementation of the `Language Server Protocol
-<https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang.
-Clangd's goal is to provide language "smartness" features like code completion,
-find references, etc. for clients such as C/C++ Editors.
-
-Using Clangd
-==================
-
-:program:`Clangd` is not meant to be used by C/C++ developers directly but
-rather from a client implementing the protocol. A client would be typically
-implemented in an IDE or an editor.
-
-At the moment, `Visual Studio Code <https://code.visualstudio.com/>`_ is mainly
-used in order to test :program:`Clangd` but more clients are likely to make
-use of :program:`Clangd` in the future as it matures and becomes a production
-quality tool. If you are interested in trying :program:`Clangd` in combination
-with Visual Studio Code, you can start by `installing Clangd`_ or
-`building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and
-launch the extension.
-
-Installing Clangd
-==================
-
-Packages are available for debian-based distributions, see the `LLVM packages
-page <https://apt.llvm.org/>`_. :program:`Clangd` is included in the
-`clang-tools` package.
-However, it is a good idea to check your distribution's packaging system first
-as it might already be available.
-
-Otherwise, you can install :program:`Clangd` by `building Clangd`_ first.
-
-Building Clangd
-==================
-
-You can follow the instructions for `building Clang
-<https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not**
-optional.
-
-Current Status
-==================
-
-Many features could be implemented in :program:`Clangd`.
-Here is a list of features that could be useful with the status of whether or
-not they are already implemented in :program:`Clangd` and specified in the
-Language Server Protocol. Note that for some of the features, it is not clear
-whether or not they should be part of the Language Server Protocol, so those
-features might be eventually developed outside :program:`Clangd` or as an
-extension to the protocol.
-
-+-------------------------------------+------------+----------+
-| C/C++ Editor feature | LSP | Clangd |
-+=====================================+============+==========+
-| Formatting | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Completion | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Diagnostics | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Fix-its | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Go to Definition | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Signature Help | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Document Highlights | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Rename | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Source hover | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Find References | Yes | No |
-+-------------------------------------+------------+----------+
-| Code Lens | Yes | No |
-+-------------------------------------+------------+----------+
-| Document Symbols | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Workspace Symbols | Yes | Yes |
-+-------------------------------------+------------+----------+
-| Syntax and Semantic Coloring | No | No |
-+-------------------------------------+------------+----------+
-| Code folding | No | No |
-+-------------------------------------+------------+----------+
-| Call hierarchy | No | No |
-+-------------------------------------+------------+----------+
-| Type hierarchy | No | No |
-+-------------------------------------+------------+----------+
-| Organize Includes | No | No |
-+-------------------------------------+------------+----------+
-| Quick Assist | No | No |
-+-------------------------------------+------------+----------+
-| Extract Local Variable | No | No |
-+-------------------------------------+------------+----------+
-| Extract Function/Method | No | No |
-+-------------------------------------+------------+----------+
-| Hide Method | No | No |
-+-------------------------------------+------------+----------+
-| Implement Method | No | No |
-+-------------------------------------+------------+----------+
-| Gen. Getters/Setters | No | No |
-+-------------------------------------+------------+----------+
-
-Editor Integration
-==================
-
-Any full-featured Language Server Protocol Client implementation should work
-with :program:`Clangd`. This `list
-<https://langserver.org/#implementations-client>`_ contains information about
-extensions and plugins that are known to work for different editors.
-
-Vim Integration
----------------
-
-LanguageClient-neovim
-~~~~~~~~~~~~~~~~~~~~~
-
-One of the options of using :program:`Clangd` in :program:`vim` (or
-:program:`nvim`) is to utilize `LanguageClient-neovim
-<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the
-`Clangd Wiki page
-<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for
-instructions.
-
-VSCode Integration
-------------------
-
-:program:`VSCode` provides `vscode-clangd
-<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_
-which is published in Visual Studio Marketplace and can be installed direcetly
-from :program:`VSCode`.
-
-Emacs Integration
------------------
-
-:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and
-`Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration.
-
-Project-wide Index
-==================
+ Installation
+ Features
-By default :program:`Clangd` only has a view on symbols coming from files you
-are currently editing. You can extend this view to whole project by providing a
-project-wide index to :program:`Clangd`.
+What is clangd?
+===============
-There are two ways you can generate a project-wide index for clangd:
+clangd understands your C++ code and adds smart features to your editor: code
+completion, compile errors, go-to-definition and more.
-- Passing experimental `-background-index` commandline argument, which will
- incrementally build an index of projects that you work on and make use of that
- in clangd automatically.
-- Generate an index file using `clangd-indexer
- <https://github.com/llvm-mirror/clang-tools-extra/blob/master/clangd/indexer/IndexerMain.cpp>`_
- Afterwards you can pass generated index file to clangd using
- `-index-file=/path/to/index_file`. *Note that clangd-indexer isn't included
- alongside clangd in the standard clang-tools package. You will likely have to
- build from source to use this option*
+clangd is a language server that implements the `Language Server Protocol
+<https://github.com/Microsoft/language-server-protocol>`__; it can work with
+many editors through a plugin. Here's Visual Studio Code with the clangd
+plugin, demonstrating code completion:
-Getting Involved
-==================
+.. image:: CodeCompletionInVSCode.png
+ :align: center
+ :alt: Code completion in VSCode
-A good place for interested contributors is the `Clangd developer mailing list
-<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the
-broader community on topics not only related to Clangd, use
-`Clang developer mailing list
-<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
-If you're also interested in contributing patches to :program:`Clangd`, take a
-look at the `LLVM Developer Policy
-<https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews
-<https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features
-to the `Language Server Protocol
-<https://github.com/Microsoft/language-server-protocol>`_ itself would also be
-very useful, so that :program:`Clangd` can eventually implement them in a
-conforming way.
+clangd is based on the `Clang <https://clang.llvm.org>`__ C++ compiler, and is
+part of the `LLVM <https://llvm.org>`__ project.
Index: clang-tools-extra/docs/clangd/Installation.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd/Installation.rst
@@ -0,0 +1,369 @@
+===========================
+Getting started with clangd
+===========================
+
+.. role:: raw-html(raw)
+ :format: html
+
+To use clangd, you need to:
+
+- install clangd,
+- install a plugin for your editor,
+- tell clangd how your project is built.
+
+Installing clangd
+=================
+
+You need a **recent** version of clangd: 7.0 was the first usable release, and
+8.0 is much better.
+
+After installing, ``clangd --version`` should print ``clangd version 7.0.0`` or
+later.
+
+:raw-html:`<details><summary markdown="span">macOS</summary>`
+
+`Homebrew <https://brew.sh>`__ can install clangd along with LLVM:
+
+.. code-block:: console
+
+ $ brew install llvm
+
+If you don't want to use Homebrew, you can download the a binary release of
+LLVM from `releases.llvm.org <http://releases.llvm.org/download.html>`__.
+Alongside ``bin/clangd`` you will need at least ``lib/clang/*/include``:
+
+.. code-block:: console
+
+ $ cp clang+llvm-7.0.0/bin/clangd /usr/local/bin/clangd
+ $ cp -r clang+llvm-7.0.0/lib/clang/ /usr/local/lib/
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Windows</summary>`
+
+Download and run the LLVM installer from `releases.llvm.org
+<http://releases.llvm.org/download.html>`__.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Debian/Ubuntu</summary>`
+
+The ``clang-tools`` package usually contains an old version of clangd.
+
+Try to install the latest release (8.0):
+
+.. code-block:: console
+
+ $ sudo apt-get install clang-tools-8
+
+If that is not found, at least ``clang-tools-7`` should be available.
+
+The ``clangd`` executable will be installed as ``/usr/bin/clangd-8``. Make it
+the default ``clangd``:
+
+.. code-block:: console
+
+ $ sudo update-alternatives --install /usr/bin/clangd clangd /usr/bin/clangd-8 100
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Other systems</summary>`
+
+Most distributions include clangd in a ``clang-tools`` package, or in the full
+``llvm`` distribution.
+
+For some platforms, binaries are also avaliable at `releases.llvm.org
+<http://releases.llvm.org/download.html>`__.
+
+:raw-html:`</details>`
+
+Editor plugins
+==============
+
+Language Server plugins are available for many editors. In principle, clangd
+should work with any of them, though the feature set and UI may vary.
+
+Here are some plugins we know work well with clangd.
+
+:raw-html:`<details><summary markdown="span">YouCompleteMe for Vim</summary>`
+
+`YouCompleteMe <https://valloric.github.io/YouCompleteMe/>`__ supports clangd.
+However, clangd support is not turned on by default, so you must install
+YouCompleteMe with ``install.py --clangd-completer``.
+
+We recommend changing a couple of YCM's default settings. In ``.vimrc`` add:
+
+::
+
+ " Let clangd fully control code completion
+ let g:ycm_clangd_uses_ycmd_caching = 0
+ " Use installed clangd, not YCM-bundled clangd which doesn't get updates.
+ let g:ycm_clangd_binary_path = exepath("clangd")
+
+You should see errors highlighted and code completions as you type.
+
+.. image:: CodeCompletionInYCM.png
+ :align: center
+ :alt: Code completion in YouCompleteMe
+
+YouCompleteMe supports many of clangd's features:
+
+- code completion,
+- diagnostics and fixes (``:YcmCompleter FixIt``),
+- find declarations, references, and definitions (``:YcmCompleter GoTo`` etc),
+- rename symbol (``:YcmCompleter RefactorRename``).
+
+**Under the hood**
+
+- **Debug logs**: run ``:YcmDebugInfo`` to see clangd status, and ``:YcmToggleLogs``
+ to view clangd's debug logs.
+- **Command-line flags**: Set ``g:ycm_clangd_args`` in ``.vimrc``, e.g.:
+
+ ::
+
+ let g:ycm_clangd_args = ['-log=verbose', '-pretty']
+
+- **Alternate clangd binary**: set ``g:ycm_clangd_binary_path`` in ``.vimrc``.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">LanguageClient for Vim and Neovim</summary>`
+
+`LanguageClient-neovim <https://github.com/autozimu/LanguageClient-neovim>`__
+has `instructions for using clangd
+<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`__, and **may**
+be easier to install than YouCompleteMe.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Eglot for Emacs</summary>`
+
+`eglot <https://github.com/joaotavora/eglot>`__ can be configured to work with
+clangd.
+
+Install eglot with ``M-x package-install RET eglot RET``.
+
+Add the following to ``~/.emacs`` to enable clangd:
+
+::
+
+ (require 'eglot)
+ (add-to-list 'eglot-server-programs '((c++-mode c-mode) "clangd"))
+ (add-hook 'c-mode-hook 'eglot-ensure)
+ (add-hook 'c++-mode-hook 'eglot-ensure)
+
+After restarting you should see diagnostics for errors in your code, and ``M-x
+completion-at-point`` should work.
+
+.. image:: DiagnosticsInEmacsEglot.png
+ :align: center
+ :alt: Diagnostics in Emacs
+
+eglot supports many of clangd's features, with caveats:
+
+- code completion, though the interaction is quite poor (even with
+ ``company-mode``, see below),
+- diagnostics and fixes,
+- find definitions and references (``M-x xref-find-definitions`` etc),
+- hover and highlights,
+- code actions (``M-x eglot-code-actions``).
+
+**company-mode**
+
+eglot does have basic integration with company-mode, which provides a more
+fluent completion UI.
+
+You can install it with ``M-x package-install RET company RET``, and enable it
+with ``M-x company-mode``.
+
+**company-clang is enabled by default**, and will interfere with clangd.
+Disable it in ``M-x customize-variable RET company-backends RET``.
+
+Completion still has some major limitations:
+
+- completions are alphabetically sorted, not ranked.
+- only pure-prefix completions are shown - no fuzzy matches.
+- completion triggering seems to be a bit hit-and-miss.
+
+.. image:: CodeCompletionInEmacsCompanyMode.png
+ :align: center
+ :alt: Completion in company-mode
+
+**Under the hood**
+
+- **Debug logs**: available in the ``EGLOT stderr`` buffer.
+- **Command-line flags and alternate binary**: instead of adding ``"clangd"``
+ to ``eglot-server-programs``, add ``("/path/to/clangd" "-log=verbose")`` etc.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Visual Studio Code</summary>`
+
+The official extension is `vscode-clangd
+<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`__
+and can be installed from within VSCode.
+
+Choose **View** --> **Extensions**, then search for "clangd". (Make sure the
+Microsoft C/C++ extension is **not** installed).
+
+After restarting, you should see red underlines underneath errors, and you
+should get rich code completions including e.g. function parameters.
+
+.. image:: CodeCompletionInVSCode.png
+ :align: center
+ :alt: Code completion in VSCode
+
+vscode-clangd has excellent support for all clangd features, including:
+
+- code completion
+- diagnostics and fixes
+- find declarations, references, and definitions
+- find symbol in file (``Ctrl-P @foo``) or workspace (``Ctrl-P #foo``)
+- hover and highlights
+- code actions
+
+**Under the hood**
+
+- **Debug logs**: when clangd is running, you should see "Clang Language
+ Server" in the dropdown of the Output panel (**View** -> **Output**).
+
+- **Command-line flags**: these can be passed in the ``clangd.arguments`` array
+ in your ``settings.json``. (**File** -> **Preferences** -> **Settings**).
+
+- **Alternate clangd binary**: set the ``clangd.path`` string in
+ ``settings.json``.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Sublime Text</summary>`
+
+`tomv564/LSP <https://github.com/tomv564/LSP>`__ works with clangd out of the box.
+
+Select **Tools** --> **Install Package Control** (if you haven't installed it
+yet).
+
+Press ``Ctrl-Shift-P`` and select **Package Control: Install Package**. Select
+**LSP**.
+
+Press ``Ctrl-Shift-P`` and select **LSP: Enable Language Server Globally**.
+Select **clangd**.
+
+Open a C++ file, and you should see diagnostics and completion:
+
+.. image:: CodeCompletionInSublimeText.png
+ :align: center
+ :alt: Code completion in Sublime Text
+
+
+The LSP package has excellent support for all most clangd features, including:
+
+- code completion (a bit noisy due to how snippets are presented)
+- diagnostics and fixes
+- find definition and references
+- hover and highlights
+- code actions
+
+**Under the hood**
+
+Settings can be tweaked under **Preferences** --> **Package Settings** -->
+**LSP**.
+
+- **Debug logs**: add ``"log_stderr": true``
+- **Command-line flags and alternate clangd binary**: inside the ``"clients":
+ {"clangd": { ... } }`` section, add ``"command": ["/path/to/clangd",
+ "-log=verbose"]`` etc.
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Other editors</summary>`
+
+There is a directory of LSP clients at `langserver.org
+<http://langserver.org>`__.
+
+A generic client should be configured to run the command ``clangd``, and
+communicate via the language server protocol on standard input/output.
+
+If you don't have strong feelings about an editor, we suggest you try out
+`VSCode <https://code.visualstudio.com/>`__, it has excellent language server
+support and most faithfully demonstrates what clangd can do.
+
+:raw-html:`</details>`
+
+Project setup
+=============
+
+To understand source code in your project, clangd needs to know the build
+flags. (This is just a fact of life in C++, source files are not
+self-contained.)
+
+By default, clangd will assume that source code is built as ``clang
+some_file.cc``, and you'll probably get spurious errors about missing
+``#include``\ d files, etc. There are a couple of ways to fix this.
+
+``compile_commands.json``
+-------------------------
+
+``compile_commands.json`` file provides compile commands for all source files
+in the project. This file is usually generated by the build system, or tools
+integrated with the build system. Clangd will look for this file in the parent
+directories of the files you edit.
+
+:raw-html:`<details><summary markdown="span">CMake-based projects</summary>`
+
+If your project builds with CMake, it can generate ``compile_commands.json``.
+You should enable it with:
+
+::
+
+ $ cmake -DCMAKE_EXPORT_COMPILE_COMMANDS=1
+
+``compile_commands.json`` will be written to your build directory. You should
+symlink it (or copy it) to the root of your source tree, if they are different.
+
+::
+
+ $ ln -s ~/myproject/compile_commands.json ~/myproject-build/
+
+:raw-html:`</details>`
+
+:raw-html:`<details><summary markdown="span">Other build systems, using Bear</summary>`
+
+`Bear <https://github.com/rizsotto/Bear>`__ is a tool that generates a
+``compile_commands.json`` file by recording a complete build.
+
+For a ``make``-based build, you can run ``make clean; bear make`` to generate the
+file (and run a clean build!)
+
+:raw-html:`</details>`
+
+Other tools can also generate this file. See `the compile_commands.json
+specification <https://clang.llvm.org/docs/JSONCompilationDatabase.html>`__.
+
+``compile_flags.txt``
+---------------------
+
+If all files in a project use the same build flags, you can put those flags,
+one flag per line, in ``compile_flags.txt`` in your source root.
+
+Clangd will assume the compile command is ``clang $FLAGS some_file.cc``.
+
+Creating this file by hand is a reasonable place to start if your project is
+quite simple.
+
+Project-wide Index
+==================
+
+By default clangd only has a view on symbols coming from files you are
+currently editing. You can extend this view to whole project by providing a
+project-wide index to clangd. There are two ways to do this.
+
+- Pass an experimental `-background-index` command line argument. With
+ this feature enabled, clangd incrementally builds an index of projects
+ that you work on and uses the just-built index automatically.
+
+- Generate an index file using `clangd-indexer
+ <https://github.com/llvm/llvm-project/blob/master/clang-tools-extra/clangd/indexer/IndexerMain.cpp>`__
+ Then you can pass generated index file to clangd using
+ `-index-file=/path/to/index_file`. *Note that clangd-indexer isn't
+ included alongside clangd in the Debian clang-tools package. You will
+ likely have to build clangd from source to use this option.*
Index: clang-tools-extra/docs/clangd/Features.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd/Features.rst
@@ -0,0 +1,265 @@
+========
+Features
+========
+
+.. role:: raw-html(raw)
+ :format: html
+
+Here is what clangd can do for you. Screenshots below show `VSCode
+<https://code.visualstudio.com/>`__; the available features and UI depend on
+the editor.
+
+Errors and warnings
+===================
+
+clangd runs the clang compiler on your code as you type, and shows errors and
+warnings in-place. Some errors are suppressed: diagnostics that require
+expanding templates in headers are disabled for performance reasons.
+
+:raw-html:`<details><summary markdown="span">Screenshot</summary>`
+
+.. image:: ErrorsInVSCode.png
+ :align: center
+ :alt: Demonstration of errors
+
+:raw-html:`</details>`
+
+Fixes in errors and warnings
+----------------------------
+
+The compiler can suggest fixes for many common problems automatically, and
+clangd can update the code for you.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: ApplyFixInVSCode.gif
+ :align: center
+ :alt: Applying a fix suggested by the compiler
+
+:raw-html:`</details>`
+
+**(New in v9)**
+If a missing symbol was seen in a file you've edited recently, clangd will
+suggest inserting it.
+
+clang-tidy checks
+-----------------
+
+**(New in v9)**
+clangd embeds `clang-tidy <https://clang.llvm.org/extra/clang-tidy/>`__
+which provides extra hints about code problems: bug-prone patterns,
+performance traps, and style issues.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: ApplyClangTidyFixInVSCode.gif
+ :align: center
+ :alt: Applying a fix suggested by the compiler
+
+:raw-html:`</details>`
+
+clangd respects your project's ``.clang-tidy`` file which controls the checks
+to run. Not all checks work within clangd. You must pass the ``-clang-tidy``
+flag to enable this feature.
+
+Code completion
+===============
+
+You'll see suggestions as you type based on what methods, variables, etc are
+available in this context.
+
+:raw-html:`<details><summary markdown="span">Screenshot</summary>`
+
+.. image:: CodeCompletionInVSCode.png
+ :align: center
+ :alt: Code completion demonstration
+
+:raw-html:`</details>`
+
+Abbreviating words may help you find the right result faster. If you type in
+``camelCase`` but the function you're looking for is ``snake_case``, that's OK.
+
+Insertion of namespace qualifiers and includes
+----------------------------------------------
+
+**(New in v8)**
+clangd will sometimes suggest results from other files and namespaces. In this
+case the correct qualifier and ``#include`` directive will be inserted.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: CodeCompletionInsertsNamespaceQualifiersInVSCode.gif
+ :align: center
+ :alt: Code completion inserts namespace qualifiers
+
+:raw-html:`</details>`
+
+Signature help
+--------------
+
+Some editors will show you the parameters of the function you're calling, as
+you fill them in.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: SignatureHelpInVSCode.gif
+ :align: center
+ :alt: Demonstration of the signature help feature
+
+:raw-html:`</details>`
+
+Cross-references
+================
+
+The following features let you navigate your codebase.
+
+If there is no project-wide index, cross-references work across the files
+you have opened.
+
+**(New in v9)**
+clangd will also automatically index your whole project.
+
+Find definition/declaration
+---------------------------
+
+Jump to the definition or declaration of a symbol under the cursor.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: GoToDefinitionInVSCode.gif
+ :align: center
+ :alt: Demonstration of the "Go to definition" feature
+
+:raw-html:`</details>`
+
+**(New in v9)**
+Some editors only expose "find definition"; use "find definition" on the
+definition to jump to the declaration.
+
+"Find definition" also works on ``#include`` lines, to jump to the included
+file.
+
+Find references
+---------------
+
+Show all references to a symbol under the cursor.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: FindAllReferencesInVSCode.gif
+ :align: center
+ :alt: Demonstration of the "Find all references" feature
+
+:raw-html:`</details>`
+
+Some editors will automatically highlight local references to the selected
+symbol as you move around a file.
+
+Navigation
+==========
+
+clangd informs the editor of the code structure in the current file.
+Some editors use this to present an outline view:
+
+:raw-html:`<details><summary markdown="span">Screenshot</summary>`
+
+.. image:: OutlineInVSCode.png
+ :align: center
+ :alt: Outline of a file
+
+:raw-html:`</details>`
+
+In VSCode, the outline is also presented as breadcrumbs that allow jumping to a
+symbol within the current file. Searching for symbols within the scope of the
+whole project is also possible.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: NavigationWithBreadcrumbsInVSCode.gif
+ :align: center
+ :alt: Navigation with breadcrumbs
+
+:raw-html:`</details>`
+
+Formatting
+==========
+
+clangd embeds `clang-format <https://clang.llvm.org/docs/ClangFormat.html>`__,
+which can reformat your code: fixing indentation, breaking lines, and reflowing
+comments.
+
+:raw-html:`<details><summary markdown="span">Animated demo</summary>`
+
+.. image:: FormatSelectionInVSCode.gif
+ :align: center
+ :alt: Formatting selected code
+
+:raw-html:`</details>`
+
+clangd respects your project's ``.clang-format`` file which controls styling
+options.
+
+Format-as-you-type is experimental and doesn't work well yet.
+
+Complete list of features
+=========================
+
+Here is a list of features that could be useful for editors, together with the
+implementation status in clangd, and specification in the Language Server
+Protocol.
+
+It is not clear whether or not some of the features mentioned below should be a
+part of the Language Server Protocol; those features might be eventually
+developed outside clangd or become clangd extensions to LSP.
+
++-------------------------------------+------------+----------+
+| C/C++ Editor feature | LSP | Clangd |
++=====================================+============+==========+
+| Formatting | Yes | Yes |
++-------------------------------------+------------+----------+
+| Completion | Yes | Yes |
++-------------------------------------+------------+----------+
+| Diagnostics | Yes | Yes |
++-------------------------------------+------------+----------+
+| Fix-its | Yes | Yes |
++-------------------------------------+------------+----------+
+| Go to Definition | Yes | Yes |
++-------------------------------------+------------+----------+
+| Signature Help | Yes | Yes |
++-------------------------------------+------------+----------+
+| Document Highlights | Yes | Yes |
++-------------------------------------+------------+----------+
+| Rename | Yes | Yes |
++-------------------------------------+------------+----------+
+| Source hover | Yes | Yes |
++-------------------------------------+------------+----------+
+| Find References | Yes | Yes |
++-------------------------------------+------------+----------+
+| Document Symbols | Yes | Yes |
++-------------------------------------+------------+----------+
+| Workspace Symbols | Yes | Yes |
++-------------------------------------+------------+----------+
+| Code Lens | Yes | No |
++-------------------------------------+------------+----------+
+| Code folding | Yes | No |
++-------------------------------------+------------+----------+
+| Extract Local Variable | Yes | No |
++-------------------------------------+------------+----------+
+| Extract Function/Method | Yes | No |
++-------------------------------------+------------+----------+
+| Quick Assist | Yes | No |
++-------------------------------------+------------+----------+
+| Hide Method | Yes | No |
++-------------------------------------+------------+----------+
+| Implement Method | Yes | No |
++-------------------------------------+------------+----------+
+| Gen. Getters/Setters | Yes | No |
++-------------------------------------+------------+----------+
+| Syntax and Semantic Coloring | No | No |
++-------------------------------------+------------+----------+
+| Call hierarchy | No | No |
++-------------------------------------+------------+----------+
+| Type hierarchy | No | No |
++-------------------------------------+------------+----------+
+| Organize Includes | No | No |
++-------------------------------------+------------+----------+
Index: clang-tools-extra/docs/clangd/Extensions.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd/Extensions.rst
@@ -0,0 +1,173 @@
+===================
+Protocol extensions
+===================
+
+clangd supports some features that are not in the official
+`Language Server Protocol specification
+<https://microsoft.github.io/language-server-protocol/specification>`__.
+
+We cautious about adding extensions. The most important considerations are:
+
+- **Editor support**: How many users will the feature be available to?
+- **Standardization**: Is the feature stable? Is it likely to be adopted by more
+ editors over time?
+- **Utility**: Does the feature provide a lot of value?
+- **Complexity**: Is this hard to implement in clangd, or constrain future work?
+ Is the protocol complicated?
+
+These extensions may evolve or disappear over time. If you use them, try to
+recover gracefully if the structures aren't what's expected.
+
+Switch between the implementation file and the header
+=====================================================
+
+*This extension is supported in clangd 6 and newer.*
+
+Switching between the implementation file and the header is an important
+feature for C++. A language server that understands C++ can do a better job
+than the editor.
+
+**New client->server request**: ``textDocument/switchSourceHeader``.
+
+Lets editors switch between the main source file (``*.cpp``) and header (``*.h``).
+
+Parameter: ``TextDocumentIdentifier``: an open file.
+
+Result: ``string``: the URI of the corresponding header (if a source file was
+provided) or source file (if a header was provided).
+
+If the corresponding file can't be determined, ``""`` is returned.
+
+File status
+===========
+
+*This extension is supported in clangd 8 and newer.*
+
+It is important to provide feedback to the user when the UI is not responsive.
+
+This extension provides information about activity on clangd's per-file worker
+thread. This information can be displayed to users to let them know that the
+language server is busy with something. For example, in clangd, building the
+AST blocks many other operations.
+
+**New server->client notification**: ``textDocument/clangd.fileStatus``
+
+Sent when the current activity for a file changes. Replaces previous activity
+for that file.
+
+Parameter: ``FileStatus`` object with properties:
+
+- ``uri : string``: the document whose status is being updated.
+- ``state : string``: human-readable information about current activity.
+
+**New initialization option**: ``initializationOptions.clangdFileStatus : bool``
+
+Enables receiving ``textDocument/clangd.fileStatus`` notifications.
+
+Compilation commands
+====================
+
+*This extension is supported in clangd 8 and newer.*
+
+clangd relies on knowing accurate compilation options to correctly interpret a
+file. Typically they are found in a ``compile_commands.json`` file in a
+directory that contains the file, or an ancestor directory. The following
+extensions allow editors to supply the commands over LSP instead.
+
+**New initialization option**: ``initializationOptions.compilationDatabasePath : string``
+
+Specifies the directory containing the compilation database (e.g.,
+``compile_commands.json``). This path will be used for all files, instead of
+searching their ancestor directories.
+
+**New initialization option**: ``initializationOptions.fallbackFlags : string[]``
+
+Controls the flags used when no specific compile command is found. The compile
+command will be approximately ``clang $FILE $fallbackFlags`` in this case.
+
+**New configuration setting**: ``settings.compilationDatabaseChanges : {string: CompileCommand}``
+
+Provides compile commands for files. This can also be provided on startup as
+``initializationOptions.compilationDatabaseChanges``.
+
+Keys are file paths (Not URIs!)
+
+Values are ``{workingDirectory: string, compilationCommand: string[]}``.
+
+Force diagnostics generation
+============================
+
+*This extension is supported in clangd 7 and newer.*
+
+Clangd does not regenerate diagnostics for every version of a file (e.g., after
+every keystroke), as that would be too slow. Its heuristics ensure:
+
+- diagnostics do not get too stale,
+- if you stop editing, diagnostics will catch up.
+
+This extension allows editors to force diagnostics to be generated or not
+generated at a particular revision.
+
+**New property of** ``textDocument/didChange`` **request**: ``wantDiagnostics : bool``
+
+- if true, diagnostics will be produced for exactly this version.
+- if false, diagnostics will not be produced for this version, even if there
+ are no further edits.
+- if unset, diagnostics will be produced for this version or some subsequent
+ one in a bounded amount of time.
+
+Diagnostic categories
+=====================
+
+*This extension is supported in clangd 8 and newer.*
+
+Clang compiler groups diagnostics into categories (e.g., "Inline Assembly
+Issue"). Clangd can emit these categories for interested editors.
+
+**New property of** ``Diagnostic`` **object**: ``category : string``:
+
+A human-readable name for a group of related diagnostics. Diagnostics with the
+same code will always have the same category.
+
+**New client capability**: ``textDocument.publishDiagnostics.categorySupport``:
+
+Requests that clangd send ``Diagnostic.category``.
+
+Inline fixes for diagnostics
+============================
+
+*This extension is supported in clangd 8 and newer.*
+
+LSP specifies that code actions for diagnostics (fixes) are retrieved
+asynchronously using ``textDocument/codeAction``. clangd always computes fixes
+eagerly. Providing them alongside diagnostics can improve the UX in editors.
+
+**New property of** ``Diagnostic`` **object**: ``codeActions : CodeAction[]``:
+
+All the code actions that address this diagnostic.
+
+**New client capability**: ``textDocument.publishDiagnostics.codeActionsInline : bool``
+
+Requests clangd to send ``Diagnostic.codeActions``.
+
+Symbol info request
+===================
+
+*This extension is supported in clangd 8 and newer.*
+
+**New client->server request**: ``textDocument/symbolInfo``:
+
+This request attempts to resolve the symbol under the cursor, without
+retrieving further information (like definition location, which may require
+consulting an index). This request was added to support integration with
+indexes outside clangd.
+
+Parameter: ``TextDocumentPositionParams``
+
+Response: ``SymbolDetails``, an object with properties:
+
+- ``name : string`` the unqualified name of the symbol
+- ``containerName : string`` the enclosing namespace, class etc (without
+ trailing ``::``)
+- ``usr : string``: the clang-specific "unified symbol resolution" identifier
+- ``id : string?``: the clangd-specific opaque symbol ID
Index: clang-tools-extra/docs/clangd/DeveloperDocumentation.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd/DeveloperDocumentation.rst
@@ -0,0 +1,10 @@
+==================================
+Developer documentation for clangd
+==================================
+
+.. toctree::
+ :maxdepth: 1
+
+ Extensions
+ Compiling
+ Contributing
Index: clang-tools-extra/docs/clangd/Contributing.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd/Contributing.rst
@@ -0,0 +1,14 @@
+======================
+Contributing to clangd
+======================
+
+A good place for interested contributors is the `Clangd developer mailing list
+<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with
+the broader community on topics not only related to Clangd, use `Clang
+developer mailing list <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_. If
+you're also interested in contributing patches to clangd, take a look at the
+`LLVM Developer Policy <https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code
+Reviews <https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new
+features to the `Language Server Protocol
+<https://github.com/Microsoft/language-server-protocol>`_ itself would also be
+very useful, so that clangd can eventually implement them in a conforming way.
Index: clang-tools-extra/docs/clangd/Compiling.rst
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/clangd/Compiling.rst
@@ -0,0 +1,7 @@
+================
+Compiling clangd
+================
+
+To build clangd from source, please follow the instructions for `building Clang
+<https://clang.llvm.org/get_started.html>`_ and include LLVM, Clang, and the
+"extra Clang tools" in your build.
Index: clang-tools-extra/docs/_templates/layout.html
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/_templates/layout.html
@@ -0,0 +1,3 @@
+{% extends "!layout.html" %}
+
+{% set css_files = css_files + ['_static/clang-tools-extra-styles.css'] %}
Index: clang-tools-extra/docs/_static/clang-tools-extra-styles.css
===================================================================
--- /dev/null
+++ clang-tools-extra/docs/_static/clang-tools-extra-styles.css
@@ -0,0 +1,23 @@
+details {
+ background-color: rgba(50, 150, 220, 0.08);
+ margin-bottom: 0.5em;
+ padding: 0 1em;
+ overflow-y: hidden; /* Suppress margin-collapsing */
+}
+details[open] {
+ border-bottom: 1px solid rgba(0, 0, 128, 0.2);
+ margin-bottom: 1em;
+}
+details summary {
+ font-weight: bold;
+ background-color: rgba(50, 150, 220, 0.1);
+ border-color: rgba(0, 0, 128, 0.2);
+ border-width: 1px;
+ border-style: solid none;
+ padding: 0.2em;
+ margin: 0 -1em;
+}
+details summary:hover {
+ background-color: rgba(50, 150, 220, 0.2);
+ cursor: pointer;
+}
_______________________________________________
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits
