This is an archive of the discontinued LLVM Phabricator instance.

Differential D58607

Moved clangd docs to a separate directory in preparation to restructure them into multiple files
ClosedPublic

Authored by gribozavr on Feb 25 2019, 4:35 AM.

Details

Reviewers
ilya-biryukov
Commits
rGa06e0290814d: Moved clangd docs to a separate directory in preparation to restructure them…
rL354786: Moved clangd docs to a separate directory in preparation to restructure them…
rCTE354786: Moved clangd docs to a separate directory in preparation to restructure them…

Diff Detail

Event Timeline

gribozavr created this revision.Feb 25 2019, 4:35 AM
Herald added a project: Restricted Project. · View Herald TranscriptFeb 25 2019, 4:35 AM
Herald added subscribers: jdoerfert, kadircet, arphaman and 3 others. · View Herald Transcript
Harbormaster completed remote builds in B28479: Diff 188131.Feb 25 2019, 4:38 AM
ilya-biryukov added inline comments.Feb 25 2019, 4:39 AM
clang-tools-extra/docs/clangd.rst
1

Having this does page not seem useful in the long-run.
Do we plan to remove it later? Or maybe there a way to create a redirect instead?

gribozavr marked an inline comment as done.Feb 25 2019, 4:41 AM
gribozavr added inline comments.
clang-tools-extra/docs/clangd.rst
1

Yes, it should be eventually removed. It is supposed to be a redirect -- it is the best we can do in plain HTML without access to HTTP headers.

ilya-biryukov accepted this revision.Feb 25 2019, 5:02 AM

LGTM

clang-tools-extra/docs/clangd.rst
1

Yeah, looks like it's the best we can do.

This revision is now accepted and ready to land.Feb 25 2019, 5:02 AM
Closed by commit rCTE354786: Moved clangd docs to a separate directory in preparation to restructure them… (authored by gribozavr). · Explain WhyFeb 25 2019, 5:44 AM
This revision was automatically updated to reflect the committed changes.

Revision Contents

PathSize
clang-tools-extra/
docs/
181 lines
clangd/
index.rst
clangd.rst
180 lines
2 lines

Diff 188131

clang-tools-extra/docs/clangd.rst

  • This file was copied to clang-tools-extra/docs/clangd/index.rst.
============ :orphan:
ilya-biryukovUnsubmitted
Not Done
ReplyInline Actions

Having this does page not seem useful in the long-run.
Do we plan to remove it later? Or maybe there a way to create a redirect instead?

ilya-biryukov: Having this does page not seem useful in the long-run. Do we plan to remove it later? Or maybe…
gribozavrAuthorUnsubmitted
Done
ReplyInline Actions

Yes, it should be eventually removed. It is supposed to be a redirect -- it is the best we can do in plain HTML without access to HTTP headers.

gribozavr: Yes, it should be eventually removed. It is supposed to be a redirect -- it is the best we can…
ilya-biryukovUnsubmitted
Not Done
ReplyInline Actions

Yeah, looks like it's the best we can do.

ilya-biryukov: Yeah, looks like it's the best we can do.
Clangd
============
.. contents:: All :program:`clangd` documentation was moved to the :doc:`clangd/index` pages.
.. 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
==================
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`.
There are two ways you can generate a project-wide index for clangd:
- 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*
Getting Involved
==================
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.

clang-tools-extra/docs/clangd/index.rst

  • This file was copied from clang-tools-extra/docs/clangd.rst.
============ ============
Clangd Clangd
============ ============
.. contents:: .. contents::
.. toctree:: .. toctree::
:maxdepth: 1 :maxdepth: 1
:program:`Clangd` is an implementation of the `Language Server Protocol :program:`Clangd` is an implementation of the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang. <https://github.com/Microsoft/language-server-protocol>`_ leveraging Clang.
Clangd's goal is to provide language "smartness" features like code completion, Clangd's goal is to provide language "smartness" features like code completion,
find references, etc. for clients such as C/C++ Editors. find references, etc. for clients such as C/C++ Editors.
Using Clangd Using Clangd
================== ==================
:program:`Clangd` is not meant to be used by C/C++ developers directly but :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 rather from a client implementing the protocol. A client would be typically
implemented in an IDE or an editor. implemented in an IDE or an editor.
At the moment, `Visual Studio Code <https://code.visualstudio.com/>`_ is mainly 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 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 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 quality tool. If you are interested in trying :program:`Clangd` in combination
with Visual Studio Code, you can start by `installing Clangd`_ or with Visual Studio Code, you can start by `installing Clangd`_ or
`building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and `building Clangd`_, then open Visual Studio Code in the clangd-vscode folder and
launch the extension. launch the extension.
Installing Clangd Installing Clangd
================== ==================
Packages are available for debian-based distributions, see the `LLVM packages Packages are available for debian-based distributions, see the `LLVM packages
page <https://apt.llvm.org/>`_. :program:`Clangd` is included in the page <https://apt.llvm.org/>`_. :program:`Clangd` is included in the
`clang-tools` package. `clang-tools` package.
However, it is a good idea to check your distribution's packaging system first However, it is a good idea to check your distribution's packaging system first
as it might already be available. as it might already be available.
Otherwise, you can install :program:`Clangd` by `building Clangd`_ first. Otherwise, you can install :program:`Clangd` by `building Clangd`_ first.
Building Clangd Building Clangd
================== ==================
You can follow the instructions for `building Clang You can follow the instructions for `building Clang
<https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not** <https://clang.llvm.org/get_started.html>`_ but "extra Clang tools" is **not**
optional. optional.
Current Status Current Status
================== ==================
Many features could be implemented in :program:`Clangd`. Many features could be implemented in :program:`Clangd`.
Here is a list of features that could be useful with the status of whether or 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 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 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 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 features might be eventually developed outside :program:`Clangd` or as an
extension to the protocol. extension to the protocol.
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| C/C++ Editor feature | LSP | Clangd | | C/C++ Editor feature | LSP | Clangd |
+=====================================+============+==========+ +=====================================+============+==========+
| Formatting | Yes | Yes | | Formatting | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Completion | Yes | Yes | | Completion | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Diagnostics | Yes | Yes | | Diagnostics | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Fix-its | Yes | Yes | | Fix-its | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Go to Definition | Yes | Yes | | Go to Definition | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Signature Help | Yes | Yes | | Signature Help | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Document Highlights | Yes | Yes | | Document Highlights | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Rename | Yes | Yes | | Rename | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Source hover | Yes | Yes | | Source hover | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Find References | Yes | No | | Find References | Yes | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Code Lens | Yes | No | | Code Lens | Yes | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Document Symbols | Yes | Yes | | Document Symbols | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Workspace Symbols | Yes | Yes | | Workspace Symbols | Yes | Yes |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Syntax and Semantic Coloring | No | No | | Syntax and Semantic Coloring | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Code folding | No | No | | Code folding | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Call hierarchy | No | No | | Call hierarchy | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Type hierarchy | No | No | | Type hierarchy | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Organize Includes | No | No | | Organize Includes | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Quick Assist | No | No | | Quick Assist | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Extract Local Variable | No | No | | Extract Local Variable | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Extract Function/Method | No | No | | Extract Function/Method | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Hide Method | No | No | | Hide Method | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Implement Method | No | No | | Implement Method | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
| Gen. Getters/Setters | No | No | | Gen. Getters/Setters | No | No |
+-------------------------------------+------------+----------+ +-------------------------------------+------------+----------+
Editor Integration Editor Integration
================== ==================
Any full-featured Language Server Protocol Client implementation should work Any full-featured Language Server Protocol Client implementation should work
with :program:`Clangd`. This `list with :program:`Clangd`. This `list
<https://langserver.org/#implementations-client>`_ contains information about <https://langserver.org/#implementations-client>`_ contains information about
extensions and plugins that are known to work for different editors. extensions and plugins that are known to work for different editors.
Vim Integration Vim Integration
--------------- ---------------
LanguageClient-neovim LanguageClient-neovim
~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~
One of the options of using :program:`Clangd` in :program:`vim` (or One of the options of using :program:`Clangd` in :program:`vim` (or
:program:`nvim`) is to utilize `LanguageClient-neovim :program:`nvim`) is to utilize `LanguageClient-neovim
<https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the <https://github.com/autozimu/LanguageClient-neovim>`_ plugin. Please see the
`Clangd Wiki page `Clangd Wiki page
<https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for <https://github.com/autozimu/LanguageClient-neovim/wiki/Clangd>`_ for
instructions. instructions.
VSCode Integration VSCode Integration
------------------ ------------------
:program:`VSCode` provides `vscode-clangd :program:`VSCode` provides `vscode-clangd
<https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.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 which is published in Visual Studio Marketplace and can be installed direcetly
from :program:`VSCode`. from :program:`VSCode`.
Emacs Integration Emacs Integration
----------------- -----------------
:program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and :program:`Emacs` provides `lsp-mode <github.com/emacs-lsp/lsp-mode>`_ and
`Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration. `Eglot <https://github.com/joaotavora/eglot>`_ plugins for LSP integration.
Project-wide Index Project-wide Index
================== ==================
By default :program:`Clangd` only has a view on symbols coming from files you 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 are currently editing. You can extend this view to whole project by providing a
project-wide index to :program:`Clangd`. project-wide index to :program:`Clangd`.
There are two ways you can generate a project-wide index for clangd: There are two ways you can generate a project-wide index for clangd:
- Passing experimental `-background-index` commandline argument, which will - Passing experimental `-background-index` commandline argument, which will
incrementally build an index of projects that you work on and make use of that incrementally build an index of projects that you work on and make use of that
in clangd automatically. in clangd automatically.
- Generate an index file using `clangd-indexer - Generate an index file using `clangd-indexer
<https://github.com/llvm-mirror/clang-tools-extra/blob/master/clangd/indexer/IndexerMain.cpp>`_ <https://github.com/llvm-mirror/clang-tools-extra/blob/master/clangd/indexer/IndexerMain.cpp>`_
Afterwards you can pass generated index file to clangd using Afterwards you can pass generated index file to clangd using
`-index-file=/path/to/index_file`. *Note that clangd-indexer isn't included `-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 alongside clangd in the standard clang-tools package. You will likely have to
build from source to use this option* build from source to use this option*
Getting Involved Getting Involved
================== ==================
A good place for interested contributors is the `Clangd developer mailing list A good place for interested contributors is the `Clangd developer mailing list
<https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the <https://lists.llvm.org/mailman/listinfo/clangd-dev>`_. For discussions with the
broader community on topics not only related to Clangd, use broader community on topics not only related to Clangd, use
`Clang developer mailing list `Clang developer mailing list
<https://lists.llvm.org/mailman/listinfo/cfe-dev>`_. <https://lists.llvm.org/mailman/listinfo/cfe-dev>`_.
If you're also interested in contributing patches to :program:`Clangd`, take a If you're also interested in contributing patches to :program:`Clangd`, take a
look at the `LLVM Developer Policy look at the `LLVM Developer Policy
<https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews <https://llvm.org/docs/DeveloperPolicy.html>`_ and `Code Reviews
<https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features <https://llvm.org/docs/Phabricator.html>`_ page. Contributions of new features
to the `Language Server Protocol to the `Language Server Protocol
<https://github.com/Microsoft/language-server-protocol>`_ itself would also be <https://github.com/Microsoft/language-server-protocol>`_ itself would also be
very useful, so that :program:`Clangd` can eventually implement them in a very useful, so that :program:`Clangd` can eventually implement them in a
conforming way. conforming way.

clang-tools-extra/docs/index.rst

Show All 19 Lines
.. toctree:: .. toctree::
:maxdepth: 2 :maxdepth: 2
clang-tidy/index clang-tidy/index
include-fixer include-fixer
modularize modularize
pp-trace pp-trace
clang-rename clang-rename
clangd clangd/index
clang-doc clang-doc
Doxygen Documentation Doxygen Documentation
===================== =====================
The Doxygen documentation describes the **internal** software that makes up the The Doxygen documentation describes the **internal** software that makes up the
tools of clang-tools-extra, not the **external** use of these tools. The Doxygen tools of clang-tools-extra, not the **external** use of these tools. The Doxygen
documentation contains no instructions about how to use the tools, only the APIs documentation contains no instructions about how to use the tools, only the APIs
Show All 18 Lines
clang-tools-extra/docs/clangd.rst