Demystifying OCaml Syntax with Merlin and OCaml-LSP

CHANGES.md

@@ -28,6 +28,10 @@
 
 - Disable automatic completion and signature help inside comments (#1246)
 
+- Includes a new optional/configurable option to toggle syntax documentation. If
+  toggled on, allows display of sytax documentation on hover tooltips. Can be
+  controlled via environment variables and by GUI for VS code. (#1218)
+
 # 1.17.0
 
 ## Fixes

README.md

@@ -304,6 +304,36 @@ of the value needs to be non-polymorphic to construct a meaningful value.
 Tip (for VS Code OCaml Platform users): You can construct a value using a keybinding
 <kbd>Alt</kbd>+<kbd>C</kbd> or on MacOS <kbd>Option</kbd>+<kbd>C</kbd>
 
+#### Syntax Documentation
+
+> since OCaml-LSP 1.18.0
+
+OCaml-LSP can display documentation about the node under the cursor when
+the user hovers over some OCaml code. For example, hovering over the code
+snippet below will display some information about what the syntax
+is:
+
+```ocaml
+type point = {x: int; y: int}
+```
+Hovering over the above will
+display:
+```
+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
+```
+The documentation is gotten from the Merlin engine which receives
+the nodes under the cursor and infers what the syntax may be about, and
+displays the required information along with links to the manual for further
+reading. 
+
+Syntax Documentation is an optional feature and can be activated by
+using the LSP config system with the key called `syntaxDocumentation` and can
+be enabled via setting it to `{ enable: true }`.
+
 ## Debugging
 
 If you use Visual Studio Code, please see OCaml Platform extension

dune-project

@@ -67,7 +67,7 @@ possible and does not make any assumptions about IO.
   (ocamlformat-rpc-lib (>= 0.21.0))
   (odoc :with-doc)
   (ocaml (and (>= 4.14) (< 5.2)))
-  (merlin-lib (and (>= 4.9) (< 5.0)))))
+  (merlin-lib (and (>= 4.14) (< 5.0)))))
 
 (package
  (name jsonrpc)

ocaml-lsp-server.opam

@@ -43,7 +43,7 @@ depends: [
   "ocamlformat-rpc-lib" {>= "0.21.0"}
   "odoc" {with-doc}
   "ocaml" {>= "4.14" & < "5.2"}
-  "merlin-lib" {>= "4.9" & < "5.0"}
+  "merlin-lib" {>= "4.14" & < "5.0"}
 ]
 dev-repo: "git+https://github.com/ocaml/ocaml-lsp.git"
 build: [

ocaml-lsp-server/docs/ocamllsp/config.md

@@ -35,5 +35,12 @@ interface config {
   * @since 1.18
   */
   inlayHints: { enable : boolean }
+
+  /**
+  * Enable/Disable Syntax Documentation
+  * @default false
+  * @since 1.18
+  */
+  syntaxDocumentation: { enable : boolean }
 }
 ```

ocaml-lsp-server/src/config_data.ml

@@ -315,6 +315,80 @@ module DuneDiagnostics = struct
   [@@@end]
 end
 
+module SyntaxDocumentation = struct
+  type t = { enable : bool [@default false] }
+  [@@deriving_inline yojson] [@@yojson.allow_extra_fields]
+
+  let _ = fun (_ : t) -> ()
+
+  let t_of_yojson =
+    (let _tp_loc =
+       "ocaml-lsp-server/src/config_data.ml.SyntaxDocumentation.t"
+     in
+     function
+     | `Assoc field_yojsons as yojson -> (
+       let enable_field = ref Ppx_yojson_conv_lib.Option.None
+       and duplicates = ref []
+       and extra = ref [] in
+       let rec iter = function
+         | (field_name, _field_yojson) :: tail ->
+           (match field_name with
+           | "enable" -> (
+             match Ppx_yojson_conv_lib.( ! ) enable_field with
+             | Ppx_yojson_conv_lib.Option.None ->
+               let fvalue = bool_of_yojson _field_yojson in
+               enable_field := Ppx_yojson_conv_lib.Option.Some fvalue
+             | Ppx_yojson_conv_lib.Option.Some _ ->
+               duplicates := field_name :: Ppx_yojson_conv_lib.( ! ) duplicates)
+           | _ -> ());
+           iter tail
+         | [] -> ()
+       in
+       iter field_yojsons;
+       match Ppx_yojson_conv_lib.( ! ) duplicates with
+       | _ :: _ ->
+         Ppx_yojson_conv_lib.Yojson_conv_error.record_duplicate_fields
+           _tp_loc
+           (Ppx_yojson_conv_lib.( ! ) duplicates)
+           yojson
+       | [] -> (
+         match Ppx_yojson_conv_lib.( ! ) extra with
+         | _ :: _ ->
+           Ppx_yojson_conv_lib.Yojson_conv_error.record_extra_fields
+             _tp_loc
+             (Ppx_yojson_conv_lib.( ! ) extra)
+             yojson
+         | [] ->
+           let enable_value = Ppx_yojson_conv_lib.( ! ) enable_field in
+           { enable =
+               (match enable_value with
+               | Ppx_yojson_conv_lib.Option.None -> false
+               | Ppx_yojson_conv_lib.Option.Some v -> v)
+           }))
+     | _ as yojson ->
+       Ppx_yojson_conv_lib.Yojson_conv_error.record_list_instead_atom
+         _tp_loc
+         yojson
+      : Ppx_yojson_conv_lib.Yojson.Safe.t -> t)
+
+  let _ = t_of_yojson
+
+  let yojson_of_t =
+    (function
+     | { enable = v_enable } ->
+       let bnds : (string * Ppx_yojson_conv_lib.Yojson.Safe.t) list = [] in
+       let bnds =
+         let arg = yojson_of_bool v_enable in
+         ("enable", arg) :: bnds
+       in
+       `Assoc bnds
+      : t -> Ppx_yojson_conv_lib.Yojson.Safe.t)
+
+  let _ = yojson_of_t
+
+  [@@@end]
+end
+
 type t =
   { codelens : Lens.t Json.Nullable_option.t
         [@default None] [@yojson_drop_default ( = )]
@@ -324,6 +398,10 @@ type t =
         [@key "inlayHints"] [@default None] [@yojson_drop_default ( = )]
   ; dune_diagnostics : DuneDiagnostics.t Json.Nullable_option.t
         [@key "duneDiagnostics"] [@default None] [@yojson_drop_default ( = )]
+  ; syntax_documentation : SyntaxDocumentation.t Json.Nullable_option.t
+        [@key "syntaxDocumentation"]
+        [@default None]
+        [@yojson_drop_default ( = )]
   }
 [@@deriving_inline yojson] [@@yojson.allow_extra_fields]
 
@@ -337,6 +415,7 @@ let t_of_yojson =
      and extended_hover_field = ref Ppx_yojson_conv_lib.Option.None
      and inlay_hints_field = ref Ppx_yojson_conv_lib.Option.None
      and dune_diagnostics_field = ref Ppx_yojson_conv_lib.Option.None
+     and syntax_documentation_field = ref Ppx_yojson_conv_lib.Option.None
      and duplicates = ref []
      and extra = ref [] in
      let rec iter = function
@@ -362,6 +441,18 @@ let t_of_yojson =
              extended_hover_field := Ppx_yojson_conv_lib.Option.Some fvalue
            | Ppx_yojson_conv_lib.Option.Some _ ->
              duplicates := field_name :: Ppx_yojson_conv_lib.( ! ) duplicates)
+         | "syntaxDocumentation" -> (
+           match Ppx_yojson_conv_lib.( ! ) syntax_documentation_field with
+           | Ppx_yojson_conv_lib.Option.None ->
+             let fvalue =
+               Json.Nullable_option.t_of_yojson
+                 SyntaxDocumentation.t_of_yojson
+                 _field_yojson
+             in
+             syntax_documentation_field :=
+               Ppx_yojson_conv_lib.Option.Some fvalue
+           | Ppx_yojson_conv_lib.Option.Some _ ->
+             duplicates := field_name :: Ppx_yojson_conv_lib.( ! ) duplicates)
          | "inlayHints" -> (
            match Ppx_yojson_conv_lib.( ! ) inlay_hints_field with
            | Ppx_yojson_conv_lib.Option.None ->
@@ -406,11 +497,13 @@ let t_of_yojson =
          let ( codelens_value
              , extended_hover_value
              , inlay_hints_value
-             , dune_diagnostics_value ) =
+             , dune_diagnostics_value
+             , syntax_documentation_value ) =
            ( Ppx_yojson_conv_lib.( ! ) codelens_field
            , Ppx_yojson_conv_lib.( ! ) extended_hover_field
            , Ppx_yojson_conv_lib.( ! ) inlay_hints_field
-           , Ppx_yojson_conv_lib.( ! ) dune_diagnostics_field )
+           , Ppx_yojson_conv_lib.( ! ) dune_diagnostics_field
+           , Ppx_yojson_conv_lib.( ! ) syntax_documentation_field )
          in
          { codelens =
              (match codelens_value with
@@ -428,6 +521,10 @@ let t_of_yojson =
              (match dune_diagnostics_value with
              | Ppx_yojson_conv_lib.Option.None -> None
              | Ppx_yojson_conv_lib.Option.Some v -> v)
+         ; syntax_documentation =
+             (match syntax_documentation_value with
+             | Ppx_yojson_conv_lib.Option.None -> None
+             | Ppx_yojson_conv_lib.Option.Some v -> v)
          }))
    | _ as yojson ->
      Ppx_yojson_conv_lib.Yojson_conv_error.record_list_instead_atom
@@ -443,6 +540,7 @@ let yojson_of_t =
      ; extended_hover = v_extended_hover
      ; inlay_hints = v_inlay_hints
      ; dune_diagnostics = v_dune_diagnostics
+     ; syntax_documentation = v_syntax_documentation
      } ->
      let bnds : (string * Ppx_yojson_conv_lib.Yojson.Safe.t) list = [] in
      let bnds =
@@ -465,6 +563,16 @@ let yojson_of_t =
          let bnd = ("inlayHints", arg) in
          bnd :: bnds
      in
+     let bnds =
+       if None = v_syntax_documentation then bnds
+       else
+         let arg =
+           (Json.Nullable_option.yojson_of_t SyntaxDocumentation.yojson_of_t)
+             v_syntax_documentation
+         in
+         let bnd = ("syntaxDocumentation", arg) in
+         bnd :: bnds
+     in
      let bnds =
        if None = v_extended_hover then bnds
        else
@@ -497,4 +605,5 @@ let default =
   ; inlay_hints =
       Some { hint_pattern_variables = false; hint_let_bindings = false }
   ; dune_diagnostics = Some { enable = true }
+  ; syntax_documentation = Some { enable = false }
   }

ocaml-lsp-server/src/document.ml

@@ -300,13 +300,23 @@ module Merlin = struct
     | `Found s | `Builtin s -> Some s
     | _ -> None
 
+  let syntax_doc pipeline pos =
+    let res =
+      let command = Query_protocol.Syntax_document pos in
+      Query_commands.dispatch pipeline command
+    in
+    match res with
+    | `Found s -> Some s
+    | `No_documentation -> None
+
   type type_enclosing =
     { loc : Loc.t
     ; typ : string
     ; doc : string option
+    ; syntax_doc : Query_protocol.syntax_doc_result option
     }
 
-  let type_enclosing doc pos verbosity =
+  let type_enclosing doc pos verbosity ~with_syntax_doc =
     with_pipeline_exn doc (fun pipeline ->
         let command = Query_protocol.Type_enclosing (None, pos, Some 0) in
         let pipeline =
@@ -327,7 +337,12 @@ module Merlin = struct
         | [] | (_, `Index _, _) :: _ -> None
         | (loc, `String typ, _) :: _ ->
           let doc = doc_comment pipeline pos in
-          Some { loc; typ; doc })
+          let syntax_doc =
+            match with_syntax_doc with
+            | true -> syntax_doc pipeline pos
+            | false -> None
+          in
+          Some { loc; typ; doc; syntax_doc })
 
   let doc_comment doc pos =
     with_pipeline_exn doc (fun pipeline -> doc_comment pipeline pos)

ocaml-lsp-server/src/document.mli

@@ -63,16 +63,21 @@ module Merlin : sig
   val doc_comment :
     t -> Msource.position -> (* doc string *) string option Fiber.t
 
+  val syntax_doc :
+    Mpipeline.t -> Msource.position -> Query_protocol.syntax_doc_result option
+
   type type_enclosing =
     { loc : Loc.t
     ; typ : string
     ; doc : string option
+    ; syntax_doc : Query_protocol.syntax_doc_result option
     }
 
   val type_enclosing :
        t
     -> Msource.position
     -> (* verbosity *) int
+    -> with_syntax_doc:bool
     -> type_enclosing option Fiber.t
 
   val kind : t -> Kind.t