From 61f9000b25e353e410d417526ef68d05cce74913 Mon Sep 17 00:00:00 2001
From: xvw <xavier.vdw@gmail.com>
Date: Thu, 27 Jun 2024 16:28:03 +0200
Subject: [PATCH] Specification of typeEnclosing and changes entry

---
 CHANGES.md                                    |  2 +
 .../docs/ocamllsp/typeEnclosing-spec.md       | 59 +++++++++++++++++++
 2 files changed, 61 insertions(+)
 create mode 100644 ocaml-lsp-server/docs/ocamllsp/typeEnclosing-spec.md

diff --git a/CHANGES.md b/CHANGES.md
index 9ef6c41c3..09e835ed5 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -42,6 +42,8 @@
   [`ocamllsp/merlinCallCompatible`](https://github.com/ocaml/ocaml-lsp/blob/e165f6a3962c356adc7364b9ca71788e93489dd0/ocaml-lsp-server/docs/ocamllsp/merlinCallCompatible-spec.md)
   request (#1265)
 
+- Add custom [`ocamllsp/typeEnclosing`](https://github.com/ocaml/ocaml-lsp/blob/109801e56f2060caf4487427bede28b824f4f1fe/ocaml-lsp-server/docs/ocamllsp/typeEnclosing-spec.md) request (#1304)
+
 
 ## Fixes
 
diff --git a/ocaml-lsp-server/docs/ocamllsp/typeEnclosing-spec.md b/ocaml-lsp-server/docs/ocamllsp/typeEnclosing-spec.md
new file mode 100644
index 000000000..a027cd6a5
--- /dev/null
+++ b/ocaml-lsp-server/docs/ocamllsp/typeEnclosing-spec.md
@@ -0,0 +1,59 @@
+# Type Enclosing Request
+
+## Description
+
+Merlin has a concept of `type enclosing` that gets the type of ident under the
+cursor. It will highlight the ident and display its type. You can climb the
+typed-tree and display the type of bigger expressions surrounding the cursor. In
+order to keep the request stateless, the manipulation related to growing or
+shrinking enclosings is delegated to the client. This request allows to request
+type enclosing under the cursor and then its surrounding enclosings.
+
+## Client capability
+
+There is no client capability relative to this request.
+
+## Server capability
+
+- property name: `handleTypeEnclosing`
+- property type: `boolean`
+
+## Request
+
+- method: `ocamllsp/typeEnclosing`
+- params:
+
+  ```json
+  {
+    "textDocument": TextDocumentIdentifier,
+    "position": Position,
+    "index": uinteger,
+    "verbosity?": uinteger,
+    "rangeEnd?": Position
+  }
+  ```
+
+  - `index` can be used to print only one type information. This is useful to query
+    the types lazily: normally, Merlin would return the signature of all enclosing
+    modules, which can be very expensive.
+  - `verbosity` determines the number of expansions of aliases in answers.
+  - `rangeEnd` an optional end position. If provided, only enclosings that contain the
+    range `[super.position; end[` will be included in the answer.
+
+
+
+## Response
+
+```json
+{
+  "enclosings": Range[],
+  "index": uinteger,
+  "type": string
+}
+```
+
+- `enclosings`: The surrounding enclosings
+- `index` The index of the provided type result: the index corresponds to a
+  zero-indexed enclosing in the `enclosings`' array. It is the same value as the
+  one provided in this request's `TypeEnclosingParams`
+- `type`: The type of the enclosing `enclosings[index]` as a raw string