Documentation custom query (#1336)

CHANGES.md

@@ -51,6 +51,8 @@
 
 - Add custom [`ocamllsp/typeEnclosing`](https://github.com/ocaml/ocaml-lsp/blob/109801e56f2060caf4487427bede28b824f4f1fe/ocaml-lsp-server/docs/ocamllsp/typeEnclosing-spec.md) request (#1304)
 
+- Add custom [`ocamllsp/getDocumentation`](/ocaml-lsp-server/docs/ocamllsp/getDocumentation-spec.md) request (#1336)
+
 
 ## Fixes
 

ocaml-lsp-server/docs/ocamllsp/getDocumentation-spec.md

@@ -0,0 +1,54 @@
+# Documentation Request
+
+## Description
+
+ This custom request allows `odoc` documentation to be gotten without using Hover.
+
+## Client capability
+
+```js
+export interface GetDocClientCapabilities {
+	contentFormat: MarkupKind[];
+}
+```
+- `contentFormat`: Client supports the following content formats if the content property refers to a `literal of type MarkupContent`. The order describes the preferred format of the client.
+
+## Server capability
+
+- property name: `handleDocumentation`
+- property type: `boolean`
+
+
+## Request
+
+```js
+export interface GetDocParams extends TextDocumentPositionParams
+{
+    identifier?: string;
+    contentFormat?:MarkupKind;
+}
+```
+- method: `ocamllsp/getDocumentation`
+- params:
+    - `TextDocumentPositionParams`: This is an existing interface that includes:
+        - `TextDocumentIdentifier`: Specifies the document for which the request is sent. It includes a uri property that points to the document.
+        - `Position`: Specifies the position in the document for which the documentation is requested. It includes line and character properties.
+    More details can be found in the [TextDocumentPositionParams - LSP Specification](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentPositionParams).
+    - `identifier` (Optional): A string representing an identifier for which the documentation is requested. If provided, the documentation lookup will be specifically for this identifier in the context of the position in the document. If omitted, the server will automatically fetch the documentation for the identifier currently under the cursor at the given position.
+    - `contentFormat` (Optional): This parameter specifies the desired format for the returned documentation content. It can be either:
+        - `Plaintext`: The documentation will be returned in plain text format.
+        - `Markdown`: The documentation will be returned in Markdown format.
+    The type `MarkupKind` typically supports these two formats, as specified in the [MarkupKind - LSP protocol](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#markupContent).
+
+## Response
+
+```js
+result: GetDoc | null
+export interface GetDoc {
+    doc: MarkupContent;
+}
+
+```
+- `doc`: The documentation found
+- A response with null result is returned if the identifier doesn't have documentation.
+- An error is returned if the identifier is invalid.

ocaml-lsp-server/src/custom_requests/custom_request.ml

@@ -5,3 +5,4 @@ module Switch_impl_intf = Req_switch_impl_intf
 module Typed_holes = Req_typed_holes
 module Type_enclosing = Req_type_enclosing
 module Wrapping_ast_node = Req_wrapping_ast_node
+module Get_documentation = Req_get_documentation

ocaml-lsp-server/src/custom_requests/custom_request.mli

@@ -7,3 +7,4 @@ module Switch_impl_intf = Req_switch_impl_intf
 module Typed_holes = Req_typed_holes
 module Type_enclosing = Req_type_enclosing
 module Wrapping_ast_node = Req_wrapping_ast_node
+module Get_documentation = Req_get_documentation

ocaml-lsp-server/src/custom_requests/req_get_documentation.ml

@@ -0,0 +1,122 @@
+open Import
+module TextDocumentPositionParams = Lsp.Types.TextDocumentPositionParams
+
+let meth = "ocamllsp/getDocumentation"
+let capability = "handleGetDocumentation", `Bool true
+
+module GetDocClientCapabilities = struct
+  type _t = { contentFormat : MarkupKind.t list }
+
+  let _yojson_of_t { contentFormat } =
+    `Assoc
+      (`List (List.map ~f:(fun format -> MarkupKind.yojson_of_t format) contentFormat))
+  ;;
+end
+
+module GetDocParams = struct
+  type t =
+    { text_document : TextDocumentIdentifier.t
+    ; position : Position.t
+    ; identifier : string option
+    ; contentFormat : MarkupKind.t option
+    }
+
+  let t_of_yojson json =
+    let open Yojson.Safe.Util in
+    let textDocumentPosition = Lsp.Types.TextDocumentPositionParams.t_of_yojson json in
+    let identifier = json |> member "identifier" |> to_option to_string in
+    let contentFormat =
+      json |> member "contentFormat" |> to_option MarkupKind.t_of_yojson
+    in
+    { position = textDocumentPosition.position
+    ; text_document = textDocumentPosition.textDocument
+    ; identifier
+    ; contentFormat
+    }
+  ;;
+
+  let yojson_of_t { text_document; position; identifier; contentFormat } =
+    let identifier =
+      match identifier with
+      | Some ident -> [ "identifier", `String ident ]
+      | None -> []
+    in
+    let contentFormat =
+      match contentFormat with
+      | Some format -> [ "contentFormat", MarkupKind.yojson_of_t format ]
+      | None -> []
+    in
+    `Assoc
+      ((("textDocument", TextDocumentIdentifier.yojson_of_t text_document)
+        :: ("position", Position.yojson_of_t position)
+        :: identifier)
+       @ contentFormat)
+  ;;
+end
+
+module GetDoc = struct
+  type t = { doc : MarkupContent.t }
+
+  let yojson_of_t { doc } = `Assoc [ "doc", MarkupContent.yojson_of_t doc ]
+
+  let t_of_yojson json =
+    let open Yojson.Safe.Util in
+    let doc = json |> member "doc" |> MarkupContent.t_of_yojson in
+    { doc }
+  ;;
+
+  let create ~kind ~value =
+    let v =
+      match kind with
+      | MarkupKind.Markdown ->
+        (match Doc_to_md.translate value with
+         | Raw d -> d
+         | Markdown d -> d)
+      | MarkupKind.PlainText -> value
+    in
+    MarkupContent.create ~kind ~value:v
+  ;;
+end
+
+type t = GetDoc.t
+
+let t_of_yojson json = GetDoc.t_of_yojson json
+
+module Request_params = struct
+  type t = GetDocParams.t
+
+  let yojson_of_t t = GetDocParams.yojson_of_t t
+
+  let create ~text_document ~position ?(identifier = None) ?(contentFormat = None) () : t =
+    { text_document; identifier; contentFormat; position }
+  ;;
+end
+
+let dispatch ~merlin ~position ~identifier ~contentFormat =
+  Document.Merlin.with_pipeline_exn merlin (fun pipeline ->
+    let position = Position.logical position in
+    let query = Query_protocol.Document (identifier, position) in
+    let result = Query_commands.dispatch pipeline query in
+    match result with
+    | `No_documentation | `Invalid_context | `Not_found _ -> `Null
+    | `Builtin value | `File_not_found value | `Found value | `Not_in_env value ->
+      let kind =
+        match contentFormat with
+        | Some format -> format
+        | None -> MarkupKind.PlainText
+      in
+      GetDoc.yojson_of_t { doc = GetDoc.create ~kind ~value })
+;;
+
+let on_request ~params state =
+  Fiber.of_thunk (fun () ->
+    let params = (Option.value ~default:(`Assoc []) params :> Yojson.Safe.t) in
+    let GetDocParams.{ text_document; position; identifier; contentFormat } =
+      GetDocParams.t_of_yojson params
+    in
+    let uri = text_document.uri in
+    let doc = Document_store.get state.State.store uri in
+    match Document.kind doc with
+    | `Other -> Fiber.return `Null
+    | `Merlin merlin -> dispatch ~merlin ~position ~identifier ~contentFormat)
+;;

ocaml-lsp-server/src/custom_requests/req_get_documentation.mli

@@ -0,0 +1,22 @@
+open Import
+
+module Request_params : sig
+  type t
+
+  val yojson_of_t : t -> Json.t
+
+  val create
+    :  text_document:TextDocumentIdentifier.t
+    -> position:Position.t
+    -> ?identifier:string option
+    -> ?contentFormat:MarkupKind.t option
+    -> unit
+    -> t
+end
+
+type t
+
+val t_of_yojson : Json.t -> t
+val meth : string
+val capability : string * [> `Bool of bool ]
+val on_request : params:Jsonrpc.Structured.t option -> State.t -> Json.t Fiber.t

ocaml-lsp-server/src/ocaml_lsp_server.ml

@@ -94,6 +94,7 @@ let initialize_info (client_capabilities : ClientCapabilities.t) : InitializeRes
               ; Req_hover_extended.capability
               ; Req_merlin_call_compatible.capability
               ; Req_type_enclosing.capability
+              ; Req_get_documentation.capability
               ] )
         ]
     in
@@ -507,6 +508,7 @@ let on_request
        ; Req_typed_holes.meth, Req_typed_holes.on_request
        ; Req_merlin_call_compatible.meth, Req_merlin_call_compatible.on_request
        ; Req_type_enclosing.meth, Req_type_enclosing.on_request
+       ; Req_get_documentation.meth, Req_get_documentation.on_request
        ; Req_wrapping_ast_node.meth, Req_wrapping_ast_node.on_request
        ; ( Semantic_highlighting.Debug.meth_request_full
          , Semantic_highlighting.Debug.on_request_full )

ocaml-lsp-server/test/e2e-new/documentation.ml

@@ -0,0 +1,163 @@
+open Test.Import
+module Req = Ocaml_lsp_server.Custom_request.Get_documentation
+
+module Util = struct
+  let call_documentation ~position ?(identifier = None) ?(contentFormat = None) client =
+    let uri = DocumentUri.of_path "test.ml" in
+    let text_document = TextDocumentIdentifier.create ~uri in
+    let params =
+      Req.Request_params.create ~text_document ~position ~identifier ~contentFormat ()
+      |> Req.Request_params.yojson_of_t
+      |> Jsonrpc.Structured.t_of_yojson
+      |> Option.some
+    in
+    let req =
+      Lsp.Client_request.UnknownRequest { meth = "ocamllsp/getDocumentation"; params }
+    in
+    Client.request client req
+  ;;
+
+  let test ~line ~character ?identifier ?contentFormat source =
+    let position = Position.create ~character ~line in
+    let contentFormat =
+      match contentFormat with
+      | Some "markdown" -> Some MarkupKind.Markdown
+      | Some "plaintext" | _ -> Some MarkupKind.PlainText
+    in
+    let request client =
+      let open Fiber.O in
+      let+ response = call_documentation ~position ~identifier ~contentFormat client in
+      Test.print_result response
+    in
+    Helpers.test source request
+  ;;
+end
+
+let%expect_test "Documentation of simple type with no contentFormat and no identifier" =
+  let source = "type tree (** This is a comment *)" in
+  let line = 0 in
+  let character = 7 in
+  Util.test ~line ~character source;
+  [%expect {| { "doc": { "kind": "plaintext", "value": "This is a comment" } } |}]
+;;
+
+let%expect_test "Documentation of simple type with contentFormat set to markdown" =
+  let source = "type tree (** This is another comment *)" in
+  let line = 0 in
+  let character = 7 in
+  let contentFormat = "markdown" in
+  Util.test ~line ~character ~contentFormat source;
+  [%expect {| { "doc": { "kind": "markdown", "value": "This is another comment" } } |}]
+;;
+
+let%expect_test "Documentation of simple type with an identifier and contentFormat" =
+  let source =
+    "{|type tree (** This is another comment *)\n  List.iter ~f:(fun x -> x*x) [2;4]|}"
+  in
+  let line = 0 in
+  let character = 7 in
+  let identifier = "List" in
+  let contentFormat = "markdown" in
+  Util.test ~line ~character ~identifier ~contentFormat source;
+  [%expect
+    {|
+    {
+      "doc": {
+        "kind": "markdown",
+        "value": "List operations.\n\nSome functions are flagged as not tail-recursive. A tail-recursive function uses constant stack space, while a non-tail-recursive function uses stack space proportional to the length of its list argument, which can be a problem with very long lists. When the function takes several list arguments, an approximate formula giving stack usage (in some unspecified constant unit) is shown in parentheses.\n\nThe above considerations can usually be ignored if your lists are not longer than about 10000 elements.\n\nThe labeled version of this module can be used as described in the `StdLabels` module."
+      }
+    } |}]
+;;
+
+let%expect_test "Documentation of simple type with an identifier and no contentFormat" =
+  let source =
+    "{|type tree (** This is another comment *)\n  List.iter ~f:(fun x -> x*x) [2;4]|}"
+  in
+  let line = 0 in
+  let character = 7 in
+  let identifier = "List" in
+  Util.test ~line ~character ~identifier source;
+  [%expect
+    {|
+    {
+      "doc": {
+        "kind": "plaintext",
+        "value": "List operations.\n\n   Some functions are flagged as not tail-recursive.  A tail-recursive\n   function uses constant stack space, while a non-tail-recursive function\n   uses stack space proportional to the length of its list argument, which\n   can be a problem with very long lists.  When the function takes several\n   list arguments, an approximate formula giving stack usage (in some\n   unspecified constant unit) is shown in parentheses.\n\n   The above considerations can usually be ignored if your lists are not\n   longer than about 10000 elements.\n\n   The labeled version of this module can be used as described in the\n   {!StdLabels} module."
+      }
+    } |}]
+;;
+
+let%expect_test "Documentation when List module is shadowed" =
+  let source =
+    "{|\n\
+     List.iter ~f:(fun x -> x*x) [2;4]\n\
+    \ module List = struct\n\
+    \  (** This is my custom list module *)\n\
+    \  let rec iter ~f = function (** This is the custom iter module *)\n\
+    \    | [] -> () (** This is when the list is empty *)\n\
+    \    | x :: xs -> f x; iter ~f xs\n\
+     end\n\
+     List.iter ~f:(fun x -> x*x) [2;4]\n\
+     |}"
+  in
+  let line = 2 in
+  let character = 6 in
+  let identifier = "List.iter" in
+  Util.test ~line ~character ~identifier source;
+  [%expect
+    {|
+  {
+    "doc": {
+      "kind": "plaintext",
+      "value": "[iter f [a1; ...; an]] applies function [f] in turn to\n   [a1; ...; an]. It is equivalent to\n   [begin f a1; f a2; ...; f an; () end]."
+    }
+  } |}]
+;;
+
+let%expect_test "Documentation when List module is shadowed" =
+  let source =
+    "{|\n\
+     List.iter ~f:(fun x -> x*x) [2;4]\n\
+     module List = struct\n\
+    \  (** This is my custom list module *)\n\
+    \  let rec iter ~f = function (** This is the custom iter module *)\n\
+    \    | [] -> () (** This is when the list is empty *)\n\
+    \    | x :: xs -> f x; iter ~f xs\n\
+     end\n\
+     Base.List.iter ~f:(fun x -> x*x) [2;4]\n\
+     |}"
+  in
+  let line = 7 in
+  let character = 12 in
+  let identifier = "Base.List.iter" in
+  Util.test ~line ~character ~identifier source;
+  [%expect {|
+  { "doc": { "kind": "plaintext", "value": "Base.List.iter" } } |}]
+;;
+
+(* TODO: Open Issue in Merlin to investigate while this doesnt return documentation of the custom List module*)
+let%expect_test "Documentation when List module is shadowed" =
+  let source =
+    "{|\n\
+     List.iter ~f:(fun x -> x*x) [2;4]\n\
+     module List = struct\n\
+    \  (** This is my custom list module *)\n\
+    \  let rec iter ~f = function (** This is the custom iter module *)\n\
+    \    | [] -> () (** This is when the list is empty *)\n\
+    \    | x :: xs -> f x; iter ~f xs\n\
+     end\n\
+     Base.List.iter ~f:(fun x -> x*x) [2;4]\n\
+     |}"
+  in
+  let line = 2 in
+  let character = 9 in
+  Util.test ~line ~character source;
+  [%expect
+    {|
+  {
+    "doc": {
+      "kind": "plaintext",
+      "value": "List operations.\n\n   Some functions are flagged as not tail-recursive.  A tail-recursive\n   function uses constant stack space, while a non-tail-recursive function\n   uses stack space proportional to the length of its list argument, which\n   can be a problem with very long lists.  When the function takes several\n   list arguments, an approximate formula giving stack usage (in some\n   unspecified constant unit) is shown in parentheses.\n\n   The above considerations can usually be ignored if your lists are not\n   longer than about 10000 elements.\n\n   The labeled version of this module can be used as described in the\n   {!StdLabels} module."
+    }
+  } |}]
+;;