### Install OCaml-LSP from Source

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

Clones the OCaml-LSP repository, including submodules, and installs it using the provided Makefile. This method is useful for development or when specific source versions are required.

```sh
git clone --recurse-submodules http://github.com/ocaml/ocaml-lsp.git
cd ocaml-lsp
make install
```

--------------------------------

### Install OCaml-LSP with Opam

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

Installs the OCaml Language Server package using the Opam package manager. This command should be run in the target Opam switch where the server is intended to be used.

```sh
opam install ocaml-lsp-server
```

--------------------------------

### Clone and Build OCaml LSP

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

Steps to clone the OCaml LSP repository, initialize submodules, set up an Opam switch, install dependencies, and build the project. The executable is located in _build/default/ocaml-lsp-server/bin/main.exe.

```bash
# clone repo with submodules
git clone --recursive git@github.com:ocaml/ocaml-lsp.git

cd ocaml-lsp

# if you already cloned, pull submodules
git submodule update --init --recursive

# create local switch (or use global one)
opam switch --yes create .

# don't forget to set your environment to use the local switch
eval $(opam env)

# install dependencies
make install-test-deps

# build
make all

# the ocllsp executable can be found at _build/default/ocaml-lsp-server/bin/main.exe
```

--------------------------------

### Run OCaml LSP Tests

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

Command to execute the project's tests. This process requires Node.js and Yarn to be installed on the system.

```sh
$ make test
```

--------------------------------

### Completion Prefix Handling for Labels

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Improves completion logic for OCaml labels by correctly handling prefixes starting with '~' or '?'. It adjusts completions to match the prefix's starting character for better accuracy.

```APIDOC
completion:
  labelPrefixHandling: true
```

--------------------------------

### OCaml AST Node Wrapping Example

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/wrappingAstNode-spec.md

Demonstrates how the `wrappingAstNode` request works by showing cursor positions within OCaml code and the corresponding evaluated AST node ranges. The table explains the rationale for each cursor position.

```ocaml
let k = <1> 1
<2>
module M = struct<3>
  let a =
    let <4> b = 1 in
    b + 1
end
```

--------------------------------

### OCaml LSP Switch Implementation/Interface Request

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/switchImplIntf-spec.md

This request is sent from a client to an OCaml LSP server to retrieve the URIs of files that the currently open file can switch to. For example, if a user has 'foo.ml' and 'foo.mli', this request allows switching between them. If no switchable files exist in the same folder, a likely candidate for creation is returned.

```APIDOC
ocamllsp/switchImplIntf
  Description: Request sent from client to server to get URI(s) of files that the current file can switch to.
  Parameters:
    - params: DocumentUri (URI of the current document, as defined in the Language Server Protocol specification)
  Returns:
    - result: DocumentUri[] (An array of URIs for switchable files. If no files exist to switch to, a URI for the most likely candidate file is returned.)
    - error: Object containing 'code' and 'message' set in case an exception happens during the request.
  Server Capability:
    - property name: handleSwitchImplIntf
    - property type: boolean
```

--------------------------------

### LSP Hover Extended Client/Server Interaction Example

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/hoverExtended-spec.md

Illustrates how client verbosity settings affect the server's response for the `ocamllsp/hoverExtended` request. Demonstrates the concept of variable verbosity based on client calls.

```typescript
// Client calls with verbosity:
// verbosity <= 0: returns 't' (equivalent to textDocument/hover)
// verbosity = 1: returns 'int'
// Default verbosity (omitted): starts at 0, increases with subsequent calls at the same position.
```

--------------------------------

### OCaml-LSP Syntax Documentation Configuration

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

OCaml-LSP can display documentation for OCaml code nodes on hover, sourced from the Merlin engine. This feature is optional and can be enabled via LSP configuration. It provides syntax explanations and links to the OCaml manual.

```APIDOC
LSP Configuration:
  syntaxDocumentation: { enable: true }

Feature Description:
  Displays documentation for OCaml code nodes under the cursor on hover.
  Information is retrieved from the Merlin engine.
  Includes syntax explanations and manual links.

Example Hover Output:
  For `type point = {x: int; y: int}`:
  "ocaml type point = { x : int; y : int }
syntax Record type:
Allows you to define variants with a fixed set of fields, and all of the
constructors for a record variant type must have the same fields. See
Manual"

Dependencies:
  Merlin engine for documentation retrieval.
```

--------------------------------

### Configuration: Syntax Documentation on Hover

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Enables optional syntax documentation display on hover tooltips. This feature can be controlled via environment variables and GUI settings, enhancing code understanding.

```APIDOC
hover:
  syntaxDocumentation: true
```

--------------------------------

### OCaml Styleguide Conventions

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CONTRIBUTING.md

Details common OCaml naming conventions used within the ocaml-lsp project, including manifest types, conversion functions, and JSON conversion functions.

```ocaml
(* Use 't' manifest types in modules, when it makes sense; *)

(* Conversion functions respecting the naming scheme: `to_xxx` or `of_xxx`; *)

(* When you want to provide a conversion function for JSON, use the following convention: `t_of_yojson` and `yojson_of_t` to fit properly with `ppx_yojson_conv`. *)

```

--------------------------------

### Command Line Arguments

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Details command line arguments accepted by the ocaml-lsp-server, including options for client process ID and socket connections.

```APIDOC
Command Line Arguments:
  --clientProcessId <pid>
    Accepts the client process ID.

  --port <port>
    Synonym for --socket. Specifies the port for communication.

  --socket <socket>
    Specifies the socket for communication.
```

--------------------------------

### OCaml Lev: Monitor Child Process with Event Loop

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/submodules/lev/README.md

Demonstrates using the low-level Lev OCaml API to monitor a child process. It sets up an event loop, creates a child process, registers a callback for process termination, and runs the loop until completion. Requires the Lev library and Unix module.

```ocaml
open Lev

let () =
  let loop = Loop.default () in
  let stdin, stdin_w = Unix.pipe ~cloexec:true () in
  let stdout_r, stdout = Unix.pipe ~cloexec:true () in
  let stderr_r, stderr = Unix.pipe ~cloexec:true () in
  Unix.close stdin_w;
  Unix.close stdout_r;
  Unix.close stderr_r;
  let pid = 
    Unix.create_process "sh" [| "sh"; "-c"; "exit 42" |] stdin stdout stderr
  in
  let child = 
    match Child.create with 
    | Error `Unimplemented -> assert false
    | Ok create ->
        create 
          (fun t ~pid status -> 
            Child.stop t loop;
            match status with 
            | Unix.WEXITED i -> Printf.printf "%d exited with status %d\n" pid i
            | _ -> assert false)
          (Pid pid) Terminate
  in
  Child.start child loop;
  Loop.run_until_done loop;
  Child.destroy child

```

--------------------------------

### Inlay Hints

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Provides inlay hints for types on let bindings, improving code comprehension by showing inferred types directly in the editor.

```APIDOC
Inlay Hints:
  - Types on let bindings
```

--------------------------------

### TypeScript Styleguide Conventions

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CONTRIBUTING.md

Describes the use of TypeScript for end-to-end tests in ocaml-lsp and the project's reliance on the Prettier formatter for TypeScript code.

```typescript
// TypeScript is used to describe certain end-to-end tests (abbreviated as `e2e`)
// and the project uses the prettier formatter.
// But the TypeScript testsuite is deprecated (we do not allow extending them anymore. Gradually we'll rewrite them all to OCaml).

```

--------------------------------

### lsp and lsp-fiber Repository Structure

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CONTRIBUTING.md

Outlines the main directories for the generic LSP protocol implementation in OCaml and its associated fiber library.

```text
lsp/
lsp-fiber/

```

--------------------------------

### Configure OCaml-LSP Semantic Highlighting in VS Code (JSON)

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

This JSON configuration snippet demonstrates how to enable OCaml-LSP's experimental semantic highlighting feature within VS Code. It specifies the `OCAMLLSP_SEMANTIC_HIGHLIGHTING` environment variable to control the highlighting mode, with options like 'full' or 'full/delta'.

```json
{
    "ocaml.server.extraEnv": {
        "OCAMLLSP_SEMANTIC_HIGHLIGHTING": "full"
    }
}
```

--------------------------------

### OCaml-LSP Supported LSP Requests

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

This section lists the Language Server Protocol (LSP) requests supported by OCaml-LSP, indicating varying degrees of support for each. It covers core LSP features and OCaml-specific extensions.

```APIDOC
textDocument/completion
  - Supports auto-completion requests.

completionItem/resolve
  - Supports resolving additional details for completion items.

textdocument/hover
  - Provides hover information for symbols.

textDocument/signatureHelp
  - Supports signature help for function calls.

textDocument/declaration
  - Retrieves declarations of symbols.

textDocument/definition
  - Retrieves definitions of symbols.

textDocument/typeDefinition
  - Retrieves type definitions for symbols.

textDocument/implementation
  - Retrieves implementations of symbols.

textDocument/codeLens
  - Provides code lens information.

textDocument/documentHighlight
  - Highlights occurrences of symbols.

textDocument/documentSymbol
  - Lists symbols within a document.

textDocument/references
  - Finds references to symbols.

textDocument/documentColor
  - Retrieves color information for a document.

textDocument/colorPresentation
  - Provides presentations for color information.

textDocument/formatting
  - Formats the entire document.

textDocument/rangeFormatting
  - Formats a specific range within the document.

textDocument/onTypeFormatting
  - Formats the document after a specific character is typed.

textDocument/prepareRename
  - Prepares for renaming a symbol.

textDocument/foldingRange
  - Provides folding ranges for code blocks.

textDocument/selectionRange
  - Retrieves selection ranges for code.

workspace/didChangeConfiguration
  - Notifies the server about configuration changes.

workspace/symbol
  - Lists workspace symbols.
```

--------------------------------

### Add OCaml-LSP to Esy Project

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

Adds the OCaml Language Server to an Esy-managed project. This integrates the server as a dependency within the project's sandbox.

```sh
esy add @opam/ocaml-lsp-server
```

--------------------------------

### ocaml-lsp-server Repository Structure

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CONTRIBUTING.md

Details the primary directory for the ocaml-lsp-server implementation and its subdirectories for code actions and custom requests.

```text
ocaml-lsp-server/
  src/code_actions/
  src/custom_requests/

```

--------------------------------

### Configure `standardHover` Server Option

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Introduces a server option `standardHover` to control the default hover provider. When set to `false`, `textDocument/hover` requests will always return an empty result, allowing clients to manage hover behavior.

```APIDOC
standardHover: false
```

--------------------------------

### Correctly accept `--clientProcessId` flag

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Fixes the handling of the `--clientProcessId` flag, ensuring it is accepted and processed correctly by the server.

```OCaml
(* Correctly accepted --clientProcessId flag *)
```

--------------------------------

### LSP Features: Semantic Highlighting

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Enables semantic highlighting support by default, enhancing code readability by providing more detailed syntax highlighting based on semantic meaning. This feature aligns with the Language Server Protocol specification.

```APIDOC
LSP Feature: TextDocument.semanticTokens
  Enabled by default since v1.15.0.
  Specification: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_semanticTokens
```

--------------------------------

### ocamllsp/jump LSP Method for Merlin Navigation

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/merlinJump-spec.md

Documents the `ocamllsp/jump` Language Server Protocol method used for Merlin-type code navigation. It includes the request parameters (`JumpParams`) which extend standard LSP position parameters and allow specifying the jump target, and the response structure (`Jump` and `TargetPosition`) detailing the navigation targets.

```APIDOC
Server Capability:
  property name: `handleJump`
  property type: `boolean`

Request:
  method: `ocamllsp/jump`
  params: `JumpParams` extends TextDocumentPositionParams and is defined as follows:
    export interface JumpParams extends TextDocumentPositionParams {
        /**
         * The requested target of the jump, one of `fun`, `let`, `module`,
         * `module-type`, `match`, `match-next-case`, `match-prev-case`.
         *
         * If omitted, all valid targets will be considered.
         */
        target?: string;
    }

Response:
  result: `Jump`
    export interface TargetPosition {
        /**
         * The target's kind.
         */
        target: string;

        /**
         * The corresponding position in the request's document.
         */
        position: Position;
    }

    export interface Jump {
        /**
         * The list of possible targets to jump-to.
         */
        jumps: TargetPosition[];
    }
```

--------------------------------

### Fix Parsing of Completion Prefixes

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Corrects issues in parsing completion prefixes, ensuring that the language server accurately determines the context for code completion suggestions.

```APIDOC
completion:
  prefixParsing: true
```

--------------------------------

### GetDocClientCapabilities Interface

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/getDocumentation-spec.md

Defines the client's capabilities for the getDocumentation request. It specifies the supported content formats (e.g., Plaintext, Markdown) that the client can handle, ordered by preference.

```js
export interface GetDocClientCapabilities {
	contentFormat: MarkupKind[];
}
```

--------------------------------

### Formatting: ocamlformat-rpc

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Re-enables `ocamlformat-rpc` for formatting code snippets, with specific notes on usage and version requirements. Formatting of files and on Windows is not supported by this RPC mechanism.

```APIDOC
Formatting:
  - Uses `ocamlformat-rpc` for code snippets.
  - Requirements: `ocamlformat` package version > 0.21.0 or `ocamlformat-rpc` package.
  - Limitations: Does not format files or run on Windows via RPC.
```

--------------------------------

### Fix Syntax Documentation Rendering

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Resolves issues with the rendering of syntax documentation, ensuring that documentation snippets are displayed correctly and legibly in the IDE.

```APIDOC
documentation:
  syntaxRendering: true
```

--------------------------------

### Run Dune in Watch Mode

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

Executes the Dune build system in watch mode. This is recommended for OCaml-LSP users as it keeps the language server updated with the latest project build information, enabling features like real-time diagnostics.

```sh
dune build --watch
```

--------------------------------

### Fix prefix parsing for completion of object methods

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Corrects prefix parsing for completing object methods, addressing an issue where method completion might fail due to incorrect prefix handling.

```OCaml
(* Fixed object method completion prefix parsing *)
```

--------------------------------

### Custom LSP Requests: ocamllsp/construct

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Introduces a custom LSP request for 'construct' operations, likely related to OCaml pattern matching or data structure construction. This enhances code generation and manipulation capabilities.

```APIDOC
ocamllsp/construct:
  description: Generate code for data structure construction.
  parameters:
    textDocument: The document URI.
    position: The cursor position.
    variant: The constructor variant to generate.
  returns:
    Generated code snippet.
```

--------------------------------

### Custom LSP Requests: ocamllsp/getDocumentation

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Adds a custom LSP request to retrieve documentation for OCaml elements. This allows clients to display detailed information about types, functions, and other constructs.

```APIDOC
ocamllsp/getDocumentation:
  description: Retrieve documentation for a symbol.
  parameters:
    textDocument: The document URI.
    position: The cursor position.
  returns:
    Documentation string or markdown.
```

--------------------------------

### Detect document kind by merlin's suffixes config

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Improves document kind detection by using Merlin's `suffixes` configuration. This allows LSP features to work more broadly for non-standard file extensions.

```OCaml
(* Document kind detection improved using merlin suffixes *)
```

--------------------------------

### ocamllsp/construct API

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/construct-spec.md

This API method allows filling typed holes (`_`) in code. It takes a document URI and position, with optional depth and value selection parameters. The response includes the range of the hole and a list of possible substitution values.

```APIDOC
ocamllsp/construct
  Parameters:
    uri: TextDocumentIdentifier
      The identifier for the text document.
    position: Position
      The position within the document where the construct request is made.
    depth?: uinteger (default: 0)
      Specifies the recursive depth for constructing terms. If depth > 1, partial results of inferior depth are not returned.
    withValues?: "local" | "none" (default: "none")
      Determines the source of values for construction. 'local' uses values from the environment, 'none' does not.
  Response:
    position: Range
      The range in the document describing the hole to be replaced.
    result: string[]
      A list of possible substitution values for the hole.
```

--------------------------------

### TypeScript Formatting Tool

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CONTRIBUTING.md

Highlights the use of Prettier for formatting TypeScript code within the project.

```typescript
// The project uses the prettier formatter for TypeScript code.

```

--------------------------------

### Custom LSP Requests: ocamllsp/jump

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Introduces a custom LSP request for 'jump' functionality, likely related to navigating code based on Merlin's jump command. This provides an alternative for ad hoc use of the feature.

```APIDOC
ocamllsp/jump:
  description: Perform a jump operation in the code.
  parameters:
    textDocument: The document URI.
    position: The cursor position.
  returns:
    List of locations to jump to.
```

--------------------------------

### OCaml Formatting Tool

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CONTRIBUTING.md

Specifies the use of ocamlformat for maintaining code style in the OCaml codebase, referencing the configuration file.

```ocaml
# The project is configured to work with ocamlformat (version defined in the .ocamlformat file).

```

--------------------------------

### ocamllsp/typeSearch API Method and Parameters (APIDOC)

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/typeSearch-spec.md

Details the ocamllsp/typeSearch Language Server Protocol method. It outlines the request parameters, including nested TextDocumentPositionParams, query, limit, and documentation flags, as well as the structure of the response payload.

```APIDOC
ocamllsp/typeSearch:
  Method for performing type searches within a text document.

  Parameters:
    - TextDocumentPositionParams: Specifies the document and cursor position.
        - TextDocumentIdentifier: Identifies the document URI.
        - Position: Specifies the cursor position.
        (See LSP Specification for details on TextDocumentPositionParams)
    - query: string - The search pattern to match types or functions.
    - limit: int - The maximum number of results to return.
    - with_doc: bool - If true, documentation information is included in the results.
    - doc_format: string - The desired format for documentation (if with_doc is true).

  Response:
    An array of result objects, or null if no entries are found.
    Each result object contains:
      - name: string - The fully qualified name of the result.
      - typ: string - The signature of the result.
      - loc: Range - The location (start/end position) of the definition in the source code.
      - doc: object (optional) - Documentation associated with the result.
          - value: string - The documentation content.
          - kind: string - The type or format of the documentation.
      - cost: int - A numeric value representing the "cost" or distance between the result and the query.
      - constructible: string - A constructible form or template for invoking the result.
```

--------------------------------

### LSP Hover Extended API Specification

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/hoverExtended-spec.md

Defines the Language Server Protocol (LSP) extension for extended hover functionality. It includes server capabilities, request parameters, and response structure.

```APIDOC
Server Capability:
  handleHoverExtended: boolean

Request:
  method: ocamllsp/hoverExtended
  params: {
    textDocument: TextDocumentIdentifier,
    position: Position,
    verbosity?: integer
  }

Response:
  contents: MarkedString | MarkedString[] | MarkupContent;
  range?: Range;
```

--------------------------------

### Auto-completion

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Offers auto-completion for the keyword `in`, streamlining the coding process for OCaml developers.

```APIDOC
Auto-completion:
  - Keyword: `in`
```

--------------------------------

### Configure `duneDiganostics`

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Provides a configuration option to control Dune diagnostics. Setting `duneDiganostics` to `{ enable: false }` disables diagnostics generated by Dune, allowing finer control over build-related feedback.

```APIDOC
duneDiganostics: { enable: false }
```

--------------------------------

### Qualify/Unqualify module names code action

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Provides code actions to either qualify (add module prefix) or unqualify (remove module prefix) identifiers. This is useful for managing namespace conflicts and improving code readability, especially after 'open' statements.

```ocaml
open Unix

let times = Unix.times ()
let f x = x.Unix.tms_stime, x.Unix.tms_utime

```

```ocaml
open Unix

let times = times ()
let f x = x.tms_stime, x.tms_utime

```

```ocaml
open Unix

let times = Unix.times ()
let f x = x.Unix.tms_stime, x.Unix.tms_utime

```

--------------------------------

### Polymorphic variant completion

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Enhances completion support for polymorphic variants when their precise type can be determined. This fixes an issue where the backtick character was ignored during prefix construction for completion.

```ocaml
let foo (a: [`Alpha | `Beta]) = ()

foo `A<|>

```

```ocaml
let a : [`Alpha | `Beta] = `B<|>

```

--------------------------------

### OCaml Compatibility

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Ensures compatibility with newer versions of OCaml, specifically supporting builds with OCaml 5.0 and 5.1. Also notes dependency updates like `merlin-lib`.

```APIDOC
OCaml Version Support:
  - OCaml 5.0
  - OCaml 5.1

Dependency Update:
  - merlin-lib 4.9
```

--------------------------------

### Odoc Syntax Support

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Adds support for new syntax elements introduced in Odoc 2.3.0, including tables and 'codeblock output' for richer documentation generation.

```APIDOC
Odoc Syntax Support:
  - Tables
  - `codeblock output`
```

--------------------------------

### ocamllsp/wrappingAstNode API

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/wrappingAstNode-spec.md

Defines the `ocamllsp/wrappingAstNode` request for Language Server Protocol. It takes a document URI and cursor position to find the enclosing AST node range. The response is either a `Range` object or `null` if the document is empty. Includes details on server capabilities and error handling.

```APIDOC
Server Capability:
  property name: handleWrappingAstNode
  property type: boolean

Client Capability:
  nothing that should be noted

Request:
- method: ocamllsp/wrappingAstNode
- params: {
    "uri": DocumentUri,
    "position": Position
  }
  - uri: The document URI.
  - position: The cursor position.

Response:
- result: Range | null
  - Returns the range of the AST node enclosing the cursor, or null if the document is empty.
- error: code and message set in case an exception happens during the processing of the request.

Notes:
- The document URI in the request must correspond to an open document.
- Stability of this custom request is not guaranteed.

Example Rationale:
| Your cursor | Evaluated expression        | Rationale                                                                                        |
| ----------- | --------------------------- | ------------------------------------------------------------------------------------------------ |
| <1>         | `let k = 1`                 | Toplevel expression under cursor                                                                 |
| <2>         | whole code block            | Cursor is in-between, so whole "file" is evaluated                                               |
| <3>         | `module M = ... end`        | Cursor is on the module definition                                                               |
| <4>         | `let a = let b = 1 in b + 1 | "Toplevel" expression for the cursor; it's used because it's "closer" than the module definition |
```

--------------------------------

### Construct Values by Type in OCaml

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/README.md

This experimental OCaml-LSP feature allows constructing expressions based on a required type, triggered by typing a typed hole (`_`) or using a code action. It offers completions for constructors and their arguments, requiring non-polymorphic types for meaningful suggestions.

```ocaml
(* file foo.ml *)
type t = A | B of string option

(* file bar.ml *)
let v : Foo.t = _ | (* Auto-completion offers Foo.A and Foo.B _ *)

(* After triggering 'Construct an expression' on Foo.B _| *)
(* Foo.B None *)

(* After triggering on Some _| *)
(* Foo.B (Some "") *)
```

--------------------------------

### LSP Features: Communication Channels

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Supports connecting over pipes and sockets for LSP communication. Pipes on Windows are not yet supported. This relates to the LSP implementation considerations for communication channels.

```APIDOC
LSP Feature: Communication Channels
  Supported: Pipes, Sockets.
  Limitations: Pipes on Windows are not yet supported.
  Specification: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#implementationConsiderations
```

--------------------------------

### Ocamllsp Configuration Interface

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/config.md

This TypeScript interface defines the structure for ocamllsp configuration settings. These settings are communicated to the language server via the `workspace/didChangeConfiguration` notification. Each property represents a specific feature that can be enabled or disabled, often with a default value and a version since which it has been available.

```typescript
interface config {
  /**
  * Enable/Disable Extended Hover
  * @default false
  * @since 1.16
  */
  extendedHover: { enable : boolean }

  /**
  * Enable/Disable CodeLens
  * @default false
  * @since 1.16
  */
  codelens: { enable : boolean }

  /**
  * Enable/Disable Dune diagnostics
  * @default true
  * @since 1.18
  */
  duneDiagnostics: { enable : boolean }

  /**
  * Enable/Disable Inlay Hints
  * @default false
  * @since 1.18
  */
  inlayHints: { enable : boolean }

  /**
  * Enable/Disable Syntax Documentation
  * @default false
  * @since 1.18
  */
  syntaxDocumentation: { enable : boolean }

  /**
  * Enable/Disable Merlin Jump code actions
  * @default true
  * @since 1.19
  */
  merlinJumpCodeActions: { enable : boolean }
}
```

--------------------------------

### Custom LSP Requests: ocamllsp/merlinCallCompatible

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Adds a custom LSP request to check Merlin call compatibility. This feature helps in understanding function call compatibility based on Merlin's analysis.

```APIDOC
ocamllsp/merlinCallCompatible:
  description: Check Merlin call compatibility.
  parameters:
    textDocument: The document URI.
    position: The cursor position.
    argument: The argument to check.
  returns:
    Boolean indicating compatibility.
```

--------------------------------

### Custom LSP Requests: ocamllsp/typeSearch

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Adds a custom Language Server Protocol request for type searching. This enables clients to query for type information within the OCaml project.

```APIDOC
ocamllsp/typeSearch:
  description: Perform a type search query.
  parameters:
    query: The search query string.
  returns:
    List of matching types or symbols.
```

--------------------------------

### Configure `merlinJumpCodeActions`

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Allows clients to enable or disable the 'jump' code actions. By default, these actions are deactivated, but can be re-enabled via the `merlinJumpCodeActions` configuration option.

```APIDOC
merlinJumpCodeActions: true
```

--------------------------------

### Custom LSP Request: hoverExtended

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Implements a custom LSP request `ocamllsp/hoverExtended` to provide extended hover information. This is a server-specific extension to the standard hover request.

```APIDOC
Custom LSP Request: ocamllsp/hoverExtended
  Description: Provides extended hover information.
  Specification: https://github.com/ocaml/ocaml-lsp/blob/e165f6a3962c356adc7364b9ca71788e93489dd0/ocaml-lsp-server/docs/ocamllsp/hoverExtended-spec.md#L1
```

--------------------------------

### Fix Missing Super/Subscripts in Markdown Documentation

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Corrects the display of super and subscripts in markdown documentation, ensuring that mathematical or specialized notation is rendered accurately.

```APIDOC
documentation:
  markdownFormatting: { fixSuperSub: true }
```

--------------------------------

### OCaml LSP Infer Interface Request: ocamllsp/inferIntf

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/inferIntf-spec.md

Defines the custom Language Server Protocol request `ocamllsp/inferIntf` used to retrieve the inferred interface for an OCaml module. The document URI must be open before sending. This request is intended for `ocaml-vscode-platform` and may be removed without notice.

```APIDOC
ocamllsp/inferIntf Request:
  Purpose: Request the inferred interface for a given module implementation.
  Prerequisites: The document URI in the request must be open.
  Error Handling: An error will be returned if the file cannot be found.
  Warning: Custom request for `ocaml-vscode-platform` exclusively; may be removed.

  Method: ocamllsp/inferIntf
  Parameters:
    - type: DocumentUri
      description: The URI of the document for which to infer the interface.
      reference: https://microsoft.github.io/language-server-protocol/specifications/specification-current/#uri

  Response:
    - result:
      type: String
      description: The inferred interface as a string.
    - error:
      type: object
      description: Contains code and message set in case of an exception during processing.
```

--------------------------------

### ocamllsp/getDocumentation Method

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/getDocumentation-spec.md

This custom LSP method allows clients to request documentation for an identifier at a specific position within a text document. It supports specifying the desired content format and an optional identifier for targeted lookups. The server returns the documentation content or null if none is found.

```APIDOC
Method: ocamllsp/getDocumentation

Request Parameters:
  TextDocumentPositionParams: Includes TextDocumentIdentifier (with uri) and Position (with line, character).
    - TextDocumentIdentifier: Specifies the document via its uri.
    - Position: Specifies the location within the document (line, character).
  identifier (Optional): A string representing the specific identifier for which documentation is requested. If omitted, the server uses the identifier currently under the cursor.
  contentFormat (Optional): Specifies the desired format for the returned documentation. Supported values are 'Plaintext' and 'Markdown' (from MarkupKind).

Response:
  result: GetDoc | null
  GetDoc interface:
    doc: MarkupContent - The documentation content found.

Notes:
- A null result is returned if the identifier has no associated documentation.
- An error is returned if the identifier is invalid or other issues occur.
```

--------------------------------

### Configuration: Code Lens

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Allows re-enabling code lens support by explicitly setting it in the configuration. This feature was disabled by default in version 1.16.0.

```APIDOC
Configuration:
  codeLens.enable: boolean
    Enables or disables code lens support. Defaults to false in v1.16.0.
```

--------------------------------

### Stop Generating Inlay Hints on Generated Code

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Prevents the generation of inlay hints on code that is automatically generated by tools like ppx. This ensures hints are only provided for user-written code.

```APIDOC
inlayHints:
  excludeGeneratedCode: true
```

--------------------------------

### ocamllsp/merlinCallCompatible LSP Request

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/ocaml-lsp-server/docs/ocamllsp/merlinCallCompatible-specs.md

Defines a custom Language Server Protocol request to invoke Merlin commands. It allows editors to send Merlin commands and receive results, supporting both JSON and SEXP formats. This is useful for editors wanting to maintain Merlin's UI while using ocaml-lsp-server.

```APIDOC
Method: ocamllsp/merlinCallCompatible

Server Capability:
  property name: handleMerlinCallCompatible
  property type: boolean

Client Capability:
  No client capability relative to this request.

Parameters:
  {
    "uri": DocumentUri,
    "command": string, // The name of the command invoked (e.g., 'case-analysis')
    "args": string[], // Parameters passed to the command, defaults to []
    "resultAsSexp": boolean // Flag to return result in SEXP (true) or JSON (false), defaults to false
  }

Response:
  {
    "resultAsSexp": boolean, // true if the command was invoked with resultAsSexp flag, false otherwise
    "result": string // The result in string format (JSON or SEXP)
  }

Description:
  Allows Merlin commands to be invoked from LSP, in the same way as the `ocamlmerlin` binary, using a custom request. Invoking this command returns the result in the form of a character string (which can be JSON or SEXP) representing the result of a Merlin command. This makes it possible to implement clients capable of fallbacking on Merlin in the event of a missing feature.

  For an exhaustive description of what the query returns, please refer to the [Merlin Protocol](https://github.com/ocaml/merlin/blob/master/doc/dev/PROTOCOL.md)
```

--------------------------------

### OCaml 5.2 Support

Source: https://github.com/c-cube/linol/blob/main/thirdparty/lsp/CHANGES.md

Adds support for the OCaml 5.2 compiler version. This ensures compatibility and allows users to leverage the features and improvements in OCaml 5.2.

```OCaml
(* OCaml 5.2 compiler support enabled *)
```