forked from OSchip/llvm-project
272 lines
9.3 KiB
ReStructuredText
272 lines
9.3 KiB
ReStructuredText
========
|
|
Features
|
|
========
|
|
|
|
.. contents::
|
|
|
|
.. 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 |Proposed [1]_| Yes |
|
|
+-------------------------------------+-------------+----------+
|
|
| Call hierarchy |Proposed [2]_| No |
|
|
+-------------------------------------+-------------+----------+
|
|
| Type hierarchy |Proposed [3]_| Yes |
|
|
+-------------------------------------+-------------+----------+
|
|
| Organize Includes | Yes | No |
|
|
+-------------------------------------+-------------+----------+
|
|
|
|
.. [1] https://github.com/microsoft/language-server-protocol/issues/18
|
|
.. [2] https://github.com/microsoft/language-server-protocol/issues/468
|
|
.. [3] https://github.com/microsoft/language-server-protocol/issues/136
|