From 2b26415f4a254a9ac75c7420cf7ae962f0dbdd67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ulysse=20G=C3=A9rard?= Date: Thu, 26 Sep 2024 18:13:42 +0200 Subject: [PATCH] [B] #1841 Document missing commands in PROTOCOL.md --- doc/dev/PROTOCOL.md | 148 +++++++++++++++++++++++++++++++++++++++----- 1 file changed, 133 insertions(+), 15 deletions(-) diff --git a/doc/dev/PROTOCOL.md b/doc/dev/PROTOCOL.md index 16fac57f0..7e84bcd7e 100644 --- a/doc/dev/PROTOCOL.md +++ b/doc/dev/PROTOCOL.md @@ -388,11 +388,13 @@ shape = ### `type-enclosing -position [ -expression ] [ -cursor ] [verbosity ] [ -index ]` - -position Position to complete - -expression Expression to type - -cursor Position of the cursor inside expression - -index Only print type of 'th result - -verbosity Verbosity level +``` + -position Position to complete + -expression Expression to type + -cursor Position of the cursor inside expression + -index Only print type of 'th result +-verbosity Verbosity level +``` Returns a list of type information for all expressions at given position, sorted by increasing size. That is asking for type enlosing around `2` in `string_of_int 2` will return the types of `2 : int` and `string_of_int 2 : string`. @@ -420,24 +422,30 @@ The result is returned as a list of: ### `type-expression -position -expression ` - -position Position to complete - -expression Expression to type +``` + -position Position to complete + -expression Expression to type +``` Returns the type of the expression when typechecked in the environment around the specified position. -### `search-by-polarity` -position -query +### `search-by-polarity -position -query ` - -position Position to search - -query The query +``` +-position Position to search + -query The query +``` Returns a list (in the form of a completion list) of values matching the query. A query is defined by polarity (and does not support type parameters). Arguments are prefixed with `-` and the return type is prefixed with `+`. For example, to find a function that takes a string and returns an integer: `-string +int`. `-list +option` will returns every definition that take a list an option. -### `search-by-type` -position -query -limit -with-doc +### `search-by-type -position -query -limit -with-doc ` - -position Position to search - -query The query - -limit a maximum-size of the result set - -with-doc if doc should be included in the result +``` +-position Position to search + -query The query + -limit The maximum-size of the result set + -with-doc If true, values' documentation will be included in the result +``` Returns a list of values matching the query. A query is a type expression, ie: `string -> int option` will search every definition that take a string and returns an option of int. It is also possible to search by polarity. @@ -454,6 +462,116 @@ The result is returned as a list of: } ``` +### `refactor-open -postion -action ` + +``` + -position Position to refactor open +-action Direction of rewriting +``` + +Returns a list of `content` and `location` (the position referenced by the `location` must be replaced by the `content`). + +The result is returned as a list of: + +```javascript +{ + 'start': position, // the start of the region to be substituted + 'end': position, // the end of the region to be substituted + 'content' string // the content of the substitution +} +``` + +### `syntax-document -position ` + + -position The position of the keyword to be documented + +Returns the string `No documentation found` (if the position does not refer to any keyword) or the following object: + +```javascript +{ + 'name': string, // the name of the keyword under the position + 'description': string, // the description of the keyword under the position + 'url': string // a reference link in the OCaml manual +} +``` + +### `expand-ppx -position ` + + -position The position where to expand the ppx preprocessors + +Returns the string `No PPX deriver/extension node found on this position` (if the position does not refer to any keyword) or the following object: + +```javascript +{ + 'code': string, // the generated code by a ppx + 'deriver': { + 'start': position, // the start of the region expanded by the ppx + 'end': position, // the end of the region expanded by the ppx + } +} +``` + +### `locate-type -position ` + + -position The position of the type to be located + +Returns the location of the type at the given position. +If the type cannot be located (because the cursor is already at the right position, or because it is a referenced built-in type, or because the type cannot be found), the result is a string explaining why it cannot be located. +The type is defined in the same file, and the result will be the following object: + +```javascript +{ + 'pos': { + 'start': position, // the start of the region where the type is defined + 'end': position // the end of the region where the type is defined + } +} +``` + +The type is described in another file, and the result will be the following object: + +```javascript +{ + 'file': string, // the file where the type is defined + 'pos': { + 'start': position, // the start of the region where the type is defined + 'end': position // the end of the region where the type is defined + } +} +``` + +### `signature-help -position ` + + -position The position where to request additional information for signature help + +This command is essentially useful for an LSP server, as it can be used to return information additional to the completion of a function and its parameters. +If no help is found, the command returns an empty object, otherwise it returns a structured object with signatures and active parameters. +You can find more information here + +### `inlay-hints -start -end -let-binding -pattern-binding -avoid-ghost ` + +``` + -start the start of the region where to activate the inlay-hints + -end the end of the region where to activate the inlay-hints + -let-binding activate for `let-bindings +-pattern-binding activate for `pattern-bindings + -avoid-ghost deactivate for node attached with a ghost location (mainly for tests) +``` + +This command is essentially useful for an LSP server, and returns the list of inlay hints for a given region in a list of the following object: + +```javascript +{ + 'pos': { + 'start': position, // the start of the region where the hint should be attached + 'end': position // the end of the region where the hint should be attached + }, + 'label': string // the value fo the hint +} +``` + +You can find more information here + ### `check-configuration`