[clangd] Group and extend release notes

clang-tools-extra/docs/ReleaseNotes.rst

@@ -47,85 +47,138 @@ Major New Features
 Improvements to clangd
 ----------------------
 
-- `clangd/inlayHints <https://clangd.llvm.org/extensions#inlay-hints>`_
-  LSP extension to provide information not directly available in code,
+Inlay hints
+^^^^^^^^^^^
+
+- This feature provides texutal hints interleaved with the code,
   like parameter names, deduced types and designated initializers.
 
-- Diagnostics and fixes for `unused include
-  <https://clangd.llvm.org/design/include-cleaner>`_ directives, according to
-  IWYU style. Off by default, can be turned on through
-  `Diagnostics.IncludeCleaner <https://clangd.llvm.org/config#unusedincludes>`_
-  config option.
+- The `clangd/inlayHints <https://clangd.llvm.org/extensions#inlay-hints>`_
+  LSP extension is now documented, and both position and range.
 
-- Support for ``textDocument/typeDefinition`` LSP request.
+- Inlay hints are now on-by-default in clangd, if the client supports and
+  exposes them. (`vscode-clangd
+  <https://marketplace.visualstudio.com/items?itemName=llvm-vs-code-extensions.vscode-clangd>`_
+  does so). The ``-inlay-hints`` flag has been removed.
 
-- Relevant diagnostics are emitted with ``Deprecated`` and ``Unnecessary``
-  tags from LSP 3.15.
+- Inlay hints can be `disabled or configured
+  <https://clangd.llvm.org/config#inlayhints>`_ in the config file.
 
-- Richer ``semanticTokens`` information for:
+Diagnostics
+^^^^^^^^^^^
 
-  - Virtual methods
-  - Mutable reference arguments
-  - Lambda captures
+- `Unused #include
+  <https://clangd.llvm.org/design/include-cleaner>`_ diagnostics are available.
+  These are off by default, and can be turned on through the
+  `Diagnostics.UnusedIncludes <https://clangd.llvm.org/config#unusedincludes>`_
+  config option.
 
-- Support for attributes, (e.g. ``[[nodiscard, gsl::Owner(Foo)]]``) in various
-  features like hover, code completion, go-to-definition.
+- ``Deprecated`` and ``Unnecessary`` tags from LSP 3.15 are set on
+  ``-Wdeprecated`` and ``-Wunused`` diagnostics. Clients may display these
+  in a specialized way.
 
-- ``#pragma mark`` directives now show up in document outline.
+- clangd suggests inserting includes to fix problems in more cases:
 
-- ``hover`` on include directives shows the resolved header path.
+  - calling unknown functions in C, even when an implicit declaration is
+    inferred.
+  - incomplete types (some additional cases).
+  - various diagnostics that specify "include <foo.h>" in their text.
 
-- ``hover`` on character literals shows their numeric value.
+- The "populate switch" action is more reliably offered as a fix for
+  ``-Wswitch`` warnings, and works with C enums.
 
-- Include desugared types in hover, controlled with `Hover.ShowAKA
-  <https://clangd.llvm.org/config#showaka>`_ config option.
+- Warnings specified by ``ExtraArgs: -W...`` flags in ``.clang-tidy`` config
+  files are now produced.
 
-- Extra diagnostic fixes to insert includes:
+Semantic Highlighting
+^^^^^^^^^^^^^^^^^^^^^
 
-  - Includes are suggested in C even when an implicit declaration is generated.
-  - Incomplete types (some additional cases).
+- ``virtual`` modifier for method names
+- ``usedAsMutableReference`` modifier for function parameters
+- Lambda captures now marked as local variables.
 
-- Code completion for ``/*ParameterName=*/`` commetns.
+Compile flags
+^^^^^^^^^^^^^
 
-- Provide and improve signature help for:
+- Compile flags like ``-xc++-header`` that must precede input file names are now
+  added correctly by the
+  `CompileFlags.Add <https://clangd.llvm.org/config#add>`_ config option.
 
-  - Variadic functions
-  - Template argument lists
-  - Braced constructor calls
-  - Aggregate initializers
-  - Constructor initializers
+- If multiple architectures are specified (e.g. when targeting Apple M1+Intel),
+  clangd will now use the host architecture instead of failing to parse.
 
-- Improved handling of short identifiers in code completion and workspace symbol
-  requests.
+- Added `CompileFlags.Compiler <https://clangd.llvm.org/config#compiler>`_
+  option to override executable name in compile flags.
 
-- Improved handling of symbols introduced via using declarations.
+- Copying ``compile_commands.json`` entries from one file to another (and simply
+  adjusting ``file``) should now work correctly.
 
-- Provide extra warnings specified in ``.clang-tidy`` config files by
-  ``ExtraArgs(Before)`` sections.
+Hover
+^^^^^
 
-- `CompileFlags.Compiler <https://clangd.llvm.org/config#compiler>`_ config
-  option to override executable name in compile flags.
+- Hovering on many attributes (e.g. ``[[nodiscard]]``) will show documentation.
+- Hovering on include directives shows the resolved header path.
+- Hovering on character literals shows their numeric value.
+- Code snippets are marked with the appropriate language instead of always C++.
+  This may improve clients' syntax highlighting.
+- Include desugared types in hover, like in diagnostics.
+  Off by default, controlled with `Hover.ShowAKA
+  <https://clangd.llvm.org/config#showaka>`_ config option.
 
-- Compile flags like ``-xc++-header`` that must precede input file names are now
-  added correctly by the
-  `CompileFlags.Add <https://clangd.llvm.org/config#add>`_ config option.
+Code completion
+^^^^^^^^^^^^^^^
+
+- Completion of attributes (e.g. ``[[gsl::Owner(Foo)]]``)
+- Completion of ``/*ParameterName=*/`` comments.
+- Documentation of items with ``annotate`` attributes now includes the
+  annotation.
+- Improved handling of results with 1-3 character names.
+- Completion of members in constructor init lists (``Foo() : member_() {}``) is
+  much more reliable.
+- C++ Standard library completions should be less noisy: parameter names are
+  deuglified (``vector<_Tp>`` is now ``vector<Tp>``) and many
+  ``__implementation_details`` are hidden altogether.
+
+Signature help
+^^^^^^^^^^^^^^
 
-- The "populate switch" code action is now offered as a fix for ``-Wswitch``
-  warnings, and works with C/ObjC enums.
+- Signatures for template argument lists
+- Signatures for braced constructor calls
+- Signatures for aggregate initializers
+- Signatures for members in constructor init lists are much more reliable.
+- Variadic functions correctly show signature help when typing the variadic
+  arguments.
+- Signature help is retriggered on closing brackets ``)``, ``}``, ``>``.
+  This means signature help should be correct after nested function calls.
 
-- ``clangd --check=/path/to/file.cpp`` now reads config files in ancestor
-  directories, in addition to user config file.
+Cross-references
+^^^^^^^^^^^^^^^^
 
-- Improved compile flags handling in ``clangd-indexer``.
+- Support for ``textDocument/typeDefinition`` LSP request.
+- Improved handling of symbols introduced via using declarations.
+- Searching for references to an overriding method also returns references to
+  the base class method. (Typically calls that may invoke the override).
+- All references from the current file are always returned, even if there are
+  enough to exceed our usual limit.
 
-- ``-use-dirty-headers`` command line flag to use dirty buffer contents when
-  parsing headers, rather than the saved on-disk contents.
+Objective-C
+^^^^^^^^^^^
 
-- Improved handling of ObjC/ObjC++ constructs.
+- ``#pragma mark`` directives now form groups in the document outline.
+- ``id`` and ``instancetype`` are treated as keywords rather than typedefs
 
-- Include request context on crashes when possible.
+Miscellaneous
+^^^^^^^^^^^^^
 
-- Various stability and performance improvements.
+- Include request context on crashes when possible.
+- Many stability, performance and correctness improvements.
+- ``-use-dirty-headers`` command line flag to use dirty buffer contents when
+  parsing headers, rather than the saved on-disk contents.
+- ``clangd --check=/path/to/file.cpp`` now reads config files in ancestor
+  directories, in addition to user config file.
+- Improved compile flags handling in ``clangd-indexer``.
+- The index file format changed in this release, indexes need to be rebuilt.
+  This should happen transparently in standard cases (the background index).
 
 Improvements to clang-doc
 -------------------------