Creating branches/google/stable and tags/google/stable/2019-05-14 from r360103upstream/stable

git-svn-id: https://llvm.org/svn/llvm-project/clang-tools-extra/branches/google/stable@360714 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 175 insertions, 0 deletions

diff --git a/docs/clangd/Extensions.rst b/docs/clangd/Extensions.rst
new file mode 100644
index 00000000..6c972ebd
--- /dev/null
+++ b/docs/clangd/Extensions.rst
@@ -0,0 +1,175 @@
+===================
+Protocol extensions
+===================
+
+.. contents::
+
+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