Update README for type hierarchy; graduate some features

README.md

@@ -67,6 +67,7 @@ Contents
  - [Diagnostic Display](#diagnostic-display)
  - [Diagnostic Highlighting Groups](#diagnostic-highlighting-groups)
  - [Symbol Search](#symbol-search)
+ - [Type/Call Hierarchy](#typecall-hierarchy)
 - [Commands](#commands)
  - [YcmCompleter subcommands](#ycmcompleter-subcommands)
  - [GoTo Commands](#goto-commands)
@@ -677,8 +678,10 @@ Quick Feature Summary
 * Code formatting (`Format`)
 * Semantic highlighting
 * Inlay hints
+* Type hierarchy
+* Call hierarchy
 
-### C♯
+### C♯ (deprecated)
 
 * Semantic auto-completion
 * Signature help
@@ -720,6 +723,7 @@ Quick Feature Summary
 * Type information for identifiers (`GetType`)
 * Code formatting (`Format`)
 * Management of `gopls` server instance
+* Call hierarchy
 
 ### JavaScript and TypeScript
 
@@ -759,6 +763,7 @@ Quick Feature Summary
 * Management of `rust-analyzer` server instance
 * Semantic highlighting
 * Inlay hints
+* Call hierarchy
 
 ### Java
 
@@ -782,6 +787,8 @@ Quick Feature Summary
 * Execute custom server command (`ExecuteCommand <args>`)
 * Management of `jdt.ls` server instance
 * Semantic highlighting
+* Type hierarchy
+* Call hierarchy
 
 User Guide
 ----------
@@ -913,10 +920,6 @@ Ctrl-l is not a suggestion, just an example.
 
 ### Semantic highlighting
 
-**NOTE**: This feature is highly experimental and offered in the hope that it is
-useful. It shall not be considered stable; if you find issues with it, feel free
-to report them, however.
-
 Semantic highlighting is the process where the buffer text is coloured according
 to the underlying semantic type of the word, rather than classic syntax
 highlighting based on regular expressions. This can be powerful additional data
@@ -1883,6 +1886,61 @@ so you can use window commands `<C-w>...` for example.
 for that, or use a window command (e.g. `<Ctrl-w>j`) or the mouse to leave the
 prompt buffer window.
 
+### Type/Call Hierarchy
+
+***This feature requires Vim and is not supported in Neovim***
+
+**NOTE**: This feature is highly experimental and offered in the hope that it is
+useful. Please help us by reporting issues and offering feedback.
+
+YCM provides a way to view and navigate hierarchies. The following hierarchies
+are supported:
+
+* Type hierachy `<Plug>(YCMTypeHierarchy)`: Display subtypes and supertypes
+ of the symbol under cursor. Expand down to subtypes and up to supertypes.
+* Call hierarchy `<Plug>(YCMCallHierarchy)`: Display callees and callers of
+ the symbol under cursor. Expand down to callers and up to callees.
+
+Take a look at this [![asciicast](https://asciinema.org/a/659925.svg)](https://asciinema.org/a/659925)
+for brief demo.
+
+Hierarchy UI can be initiated by mapping something to the indicated plug
+mappings, for example:
+
+```viml
+nmap <leader>yth <Plug>(YCMTypeHierarchy)
+nmap <leader>ych <Plug>(YCMCallHierarchy)
+```
+
+This opens a "modal" popup showing the current element in the hierarchy tree.
+The current tree root is aligned to the left and child and parent nodes are
+expanded to the right. Expand the tree "down" with `<Tab> and "up" with
+`<S-Tab>`.
+
+The "root" of the tree can be re-focused to the selected item with
+`<S-Tab>` and further `<S-Tab>` will show the parents of the selected item. This
+can take a little getting used to, but it's particularly important with multiple
+inheritance where a "child" of the current root may actually have other,
+invisible, parent links. `<S-Tab>` on that row will show these by setting the
+display root to the selected item.
+
+When the hierarchy is displayed, the following keys are intercepted:
+
+* `<Tab>`: Drill into the hierarchy at the selected item: expand and show
+ children of the selected item.
+* `<S-Tab>`: Show parents of the selected item. When applied to sub-types, this
+ will re-root the tree at that type, so that all parent types (are displayed).
+ Similar for callers.
+* `<CR>`: Jump to the symbol currently selected.
+* `<Down>`, `<C-n>`, `<C-j>`, `j`: Select the next item
+* `<Up>`, `<C-p>`, `<C-k>`, `k`; Select the previous item
+* Any other key: closes the popup without jumping to any location
+
+**Note:** you might think the call hierarchy tree is inverted, but we think
+this way round is more intuitive because this is the typical way that call
+stacks are displayed (with the current function at the top, and its callers
+below). 
+
 Commands
 --------
 
@@ -2102,6 +2160,9 @@ Supported in filetypes: `c, cpp, objc, objcpp, cuda, go, java, rust`
 
 #### The `GoToCallers` and `GoToCallees` subcommands
 
+Note: A much more powerful call and type hierarchy can be viewd interactively.
+See [interactive type and call hierarchy](#interactive-type-and-call-hierarchy).
+
 Populate the quickfix list with the callers, or callees respectively, of the
 function associated with the current cursor position. The semantics of this
 differ depending on the filetype and language server.
@@ -3738,9 +3799,7 @@ let g:ycm_language_server = []
 ### The `g:ycm_disable_signature_help` option
 
 This option allows you to disable all signature help for all completion engines.
-There is no way to disable it per-completer. This option is _reserved_, meaning
-that while signature help support remains experimental, its values and meaning
-may change and it may be removed in a future version.
+There is no way to disable it per-completer.
 
 Default: `0`