Document type/call hierarchies in the ycmd API

ycm-core · Jun 9, 2024 · a4b4bdc · a4b4bdc
1 parent ce66f8a
commit a4b4bdc
Show file tree

Hide file tree

Showing 5 changed files with 240 additions and 8 deletions.
diff --git a/docs/bundle.js.map b/docs/bundle.js.map
diff --git a/docs/index.html b/docs/index.html
@@ -2365,6 +2365,21 @@ <h3 class="panel-title"><span class="operation-name">POST</span> <strong>/run_co
  messages are typically multiple lines (such as the documentation and
  signature for a method) and are best displayed in a panel or preview
  area (or equivalent).</li>
+ <li>A <em>Hierarchy</em> response. This is identified where the type of the
+ response is a list of objects containing <code>kind</code> and <code>locations</code>
+ properties.
+ Hierarchy requests work similarly to those in the LSP specification.
+ If a completer supports call/type hierarchies, the initial request
+ should be sent through <code>TypeHierarchy</code>/<code>CallHierarchy</code> subcommand.
+ Resolving any item in the hierarchy tree is done by subsequent
+ <code>ResolveCallHierarchyItem</code> and <code>ResolveTypeHierarchyItem</code> requests.
+ When resolving a hierarchy item, the arguments following
+ the subcommand name are the item being resolved and the direction in
+ which the item should be resolved.
+ For call hierarchies, the directions are <code>incoming</code> and <code>outgoing</code>.
+ For type hierarchies, the directions are <code>subtypes</code> and <code>supertypes</code>.
+ Note that, except for the root node of the hierarchy, resolving an
+ item in both directions is discouraged.</li>
  <li>A <em>GoTo</em> response. This is identified where the response type cannot
  be determined by any of the above methods. A GoTo response may contain
  either a single location (e.g. for <code>GoToDeclaration</code>), or a list of
@@ -4524,6 +4539,121 @@ <h3 class="panel-title"><a name="/definitions/FixIt"></a>FixIt:
  </section>
  </div>
  </div> 
+ <div id="definition-Hierarchy" class="panel panel-definition">
+ <div class="panel-heading">
+ <h3 class="panel-title"><a name="/definitions/Hierarchy"></a>Hierarchy:
+ <span class="json-property-type">
+ <span class="json-property-type">object</span>
+ <span class="json-property-range" title="Value limits"></span>
+
+ </span>
+ </h3>
+ </div>
+ <div class="panel-body">
+ <section class="json-schema-description">
+ <p>An object returned, in a list, as a response to hierarchy requests.
+ The object may contain additional properties, which are used to identify
+ the hierarchy tree node, by the subservers.</p>
+
+ </section>
+
+ <section class="json-schema-properties">
+ <dl>
+ <dt data-property-name="kind">
+ <span class="json-property-name">kind:</span>
+
+ <span class="json-property-type">string</span> <span class="json-property-enum" title="Possible values">, x &isin; {
+ <span class="json-property-enum-item">File</span>
+ ,
+ <span class="json-property-enum-item">Module</span>
+ ,
+ <span class="json-property-enum-item">Namespace</span>
+ ,
+ <span class="json-property-enum-item">Package</span>
+ ,
+ <span class="json-property-enum-item">Class</span>
+ ,
+ <span class="json-property-enum-item">Method</span>
+ ,
+ <span class="json-property-enum-item">Property</span>
+ ,
+ <span class="json-property-enum-item">Field</span>
+ ,
+ <span class="json-property-enum-item">Constructor</span>
+ ,
+ <span class="json-property-enum-item">Enum</span>
+ ,
+ <span class="json-property-enum-item">Interface</span>
+ ,
+ <span class="json-property-enum-item">Function</span>
+ ,
+ <span class="json-property-enum-item">Variable</span>
+ ,
+ <span class="json-property-enum-item">Constant</span>
+ ,
+ <span class="json-property-enum-item">String</span>
+ ,
+ <span class="json-property-enum-item">Number</span>
+ ,
+ <span class="json-property-enum-item">Boolean</span>
+ ,
+ <span class="json-property-enum-item">Array</span>
+ ,
+ <span class="json-property-enum-item">Object</span>
+ ,
+ <span class="json-property-enum-item">Key</span>
+ ,
+ <span class="json-property-enum-item"></span>
+ ,
+ <span class="json-property-enum-item">EnumMember</span>
+ ,
+ <span class="json-property-enum-item">Struct</span>
+ ,
+ <span class="json-property-enum-item">Event</span>
+ ,
+ <span class="json-property-enum-item">Operator</span>
+ ,
+ <span class="json-property-enum-item">TypeParameter</span>
+
+ }
+ </span>
+ <span class="json-property-range" title="Value limits"></span>
+
+ <span class="json-property-required"></span>
+ </dt>
+ <dd>
+
+ <div class="json-inner-schema">
+
+ </div>
+ </dd>
+ <dt data-property-name="locations">
+ <span class="json-property-name">locations:</span>
+
+ <span class="json-property-type">object[]</span>
+ <span class="json-property-range" title="Value limits"></span>
+
+ <span class="json-property-required"></span>
+ </dt>
+ <dd>
+
+ <div class="json-inner-schema">
+
+ <section class="json-schema-array-items">
+
+ <span class="json-property-type"> <a class="json-schema-ref" href="#/defintions/Location">#/defintions/Location</a>
+ </span>
+ <span class="json-property-range" title="Value limits"></span>
+
+ <div class="json-inner-schema">
+
+ </div>
+ </section> </div>
+ </dd>
+ </dl>
+ </section>
+ </div>
+ </div> 
  <div id="definition-InlayHint" class="panel panel-definition">
  <div class="panel-heading">
  <h3 class="panel-title"><a name="/definitions/InlayHint"></a>InlayHint:
@@ -4548,6 +4678,8 @@ <h3 class="panel-title"><a name="/definitions/InlayHint"></a>InlayHint:
  <span class="json-property-name">kind:</span>
 
  <span class="json-property-type">string</span> <span class="json-property-enum" title="Possible values">, x &isin; {
+ <span class="json-property-enum-item">Unknown</span>
+ ,
  <span class="json-property-enum-item">Type</span>
  ,
  <span class="json-property-enum-item">Parameter</span>
@@ -5448,6 +5580,38 @@ <h3 class="panel-title"><a name="/definitions/SubcommandResponse"></a>Subcommand
 
  </div>
  </dd>
+ <dt data-property-name="kind">
+ <span class="json-property-name">kind:</span>
+
+ <span class="json-property-type">string</span>
+ <span class="json-property-range" title="Value limits"></span>
+
+ </dt>
+ <dd>
+ <p>If present, this is a <em>Hierarchy response</em> and this value
+ describes the kind of symbol a node in the call/type hierarchy
+ tree is referring to.</p>
+
+ <div class="json-inner-schema">
+
+ </div>
+ </dd>
+ <dt data-property-name="locations">
+ <span class="json-property-name">locations:</span>
+
+ <span class="json-property-type">object[]</span>
+ <span class="json-property-range" title="Value limits"></span>
+
+ </dt>
+ <dd>
+ <p>If present, this is a <em>Hierarchy response</em> and this value
+ contains a list of locations that a node in the call/type
+ hierarchy tree is referring to.</p>
+
+ <div class="json-inner-schema">
+
+ </div>
+ </dd>
  <dt data-property-name="line_num">
  <span class="json-property-name">line_num:</span>
 

diff --git a/docs/main.css.map b/docs/main.css.map
diff --git a/docs/openapi.yml b/docs/openapi.yml
@@ -190,7 +190,49 @@ definitions:
 
  additionalProperties:
  $ref: "#/definitions/FileData"
-
+ Hierarchy:
+ type: object
+ required:
+ - kind
+ - locations
+ description: |-
+ An object returned, in a list, as a response to hierarchy requests.
+ The object may contain additional properties, which are used to identify
+ the hierarchy tree node, by the subservers.
+ properties:
+ kind:
+ type: string
+ enum:
+ - File
+ - Module
+ - Namespace
+ - Package
+ - Class
+ - Method
+ - Property
+ - Field
+ - Constructor
+ - Enum
+ - Interface
+ - Function
+ - Variable
+ - Constant
+ - String
+ - Number
+ - Boolean
+ - Array
+ - Object
+ - Key
+ - Null
+ - EnumMember
+ - Struct
+ - Event
+ - Operator
+ - TypeParameter
+ locations:
+ type: array
+ items:
+ $ref: "#/defintions/Location"
  # Due to the way the API combines keys at the top level, we are not able to
  # compose this item per-request. So this definition must be copy-pasted for
  # some requests.
@@ -368,6 +410,22 @@ definitions:
  If present, this is a single *GoTo response* and this value
  contains the absolute path of the buffer containing the
  target location (identified in `line_num` and `column_num`).
+ kind:
+ type: string
+ description: |-
+ If present, this is a *Hierarchy response* and this value
+ describes the kind of symbol a node in the call/type hierarchy
+ tree is referring to.
+ hierarchy details:
+ $ref: "#/definitions/Hierarchy"
+ locations:
+ type: array
+ description: |-
+ If present, this is a *Hierarchy response* and this value
+ contains a list of locations that a node in the call/type
+ hierarchy tree is referring to.
+ hierarchy details:
+ $ref: "#/definitions/Hierarchy"
  line_num:
  $ref: "#/definitions/LineNumber"
  column_num:
@@ -886,6 +944,21 @@ paths:
  messages are typically multiple lines (such as the documentation and
  signature for a method) and are best displayed in a panel or preview
  area (or equivalent).
+ - A *Hierarchy* response. This is identified where the type of the
+ response is a list of objects containing `kind` and `locations`
+ properties.
+ Hierarchy requests work similarly to those in the LSP specification.
+ If a completer supports call/type hierarchies, the initial request
+ should be sent through `TypeHierarchy`/`CallHierarchy` subcommand.
+ Resolving any item in the hierarchy tree is done by subsequent
+ `ResolveCallHierarchyItem` and `ResolveTypeHierarchyItem` requests.
+ When resolving a hierarchy item, the arguments following
+ the subcommand name are the item being resolved and the direction in
+ which the item should be resolved.
+ For call hierarchies, the directions are `incoming` and `outgoing`.
+ For type hierarchies, the directions are `subtypes` and `supertypes`.
+ Note that, except for the root node of the hierarchy, resolving an
+ item in both directions is discouraged.
  - A *GoTo* response. This is identified where the response type cannot
  be determined by any of the above methods. A GoTo response may contain
  either a single location (e.g. for `GoToDeclaration`), or a list of

diff --git a/update_api_docs.py b/update_api_docs.py
@@ -1,10 +1,5 @@
 #!/usr/bin/env python3
 
-from __future__ import print_function
-from __future__ import division
-from __future__ import unicode_literals
-from __future__ import absolute_import
-
 import os
 import platform
 import sys