docs/clangd/Features.rst - clang-tools-extra - Git at Google

 ========
 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
	========
	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