add id:s and signatures for constructors/record fields

zth · Gabriel Nordeborn · commit bfe7cb631f06 · 2023-05-27T19:35:31.000+02:00
diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml
@@ -5,18 +5,28 @@ type linkableType = {
   loc: Location.t;
 }
 
+type fieldDoc = {fieldName: string; docstrings: string list; signature: string}
+
+type constructorDoc = {
+  constructorName: string;
+  docstrings: string list;
+  signature: string;
+}
+
 type docItemDetail =
-  | Record of {fieldDocs: (string * string list) list}
-  | Variant of {constructorDocs: (string * string list) list}
+  | Record of {fieldDocs: fieldDoc list}
+  | Variant of {constructorDocs: constructorDoc list}
 type docItem =
   | Value of {
+      id: string;
       docstring: string list;
       signature: string;
       name: string;
       linkables: linkableType list;
           (** Relevant types to link to, found in relation to this value. *)
     }
   | Type of {
+      id: string;
       docstring: string list;
       signature: string;
       name: string;
@@ -26,7 +36,12 @@ type docItem =
           (** Relevant types to link to, found in relation to this type. *)
     }
   | Module of docsForModule
-and docsForModule = {docstring: string list; name: string; items: docItem list}
+and docsForModule = {
+  id: string;
+  docstring: string list;
+  name: string;
+  items: docItem list;
+}
 
 let formatCode content =
   let {Res_driver.parsetree = signature; comments} =
@@ -130,11 +145,13 @@ let stringifyDetail ?(indentation = 0) (detail : docItemDetail) =
         ( "fieldDocs",
           Some
             (fieldDocs
-            |> List.map (fun (fieldName, docstrings) ->
+            |> List.map (fun fieldDoc ->
                    stringifyObject ~indentation:(indentation + 1)
                      [
-                       ("fieldName", Some (wrapInQuotes fieldName));
-                       ("docstrings", Some (stringifyDocstrings docstrings));
+                       ("fieldName", Some (wrapInQuotes fieldDoc.fieldName));
+                       ( "docstrings",
+                         Some (stringifyDocstrings fieldDoc.docstrings) );
+                       ("signature", Some (wrapInQuotes fieldDoc.signature));
                      ])
             |> array) );
       ]
@@ -145,22 +162,27 @@ let stringifyDetail ?(indentation = 0) (detail : docItemDetail) =
         ( "fieldDocs",
           Some
             (constructorDocs
-            |> List.map (fun (constructorName, docstrings) ->
+            |> List.map (fun constructorDoc ->
                    stringifyObject ~startOnNewline:true
                      ~indentation:(indentation + 1)
                      [
-                       ("constructorName", Some (wrapInQuotes constructorName));
-                       ("docstrings", Some (stringifyDocstrings docstrings));
+                       ( "constructorName",
+                         Some (wrapInQuotes constructorDoc.constructorName) );
+                       ( "docstrings",
+                         Some (stringifyDocstrings constructorDoc.docstrings) );
+                       ( "signature",
+                         Some (wrapInQuotes constructorDoc.signature) );
                      ])
             |> array) );
       ]
 
 let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) =
   let open Protocol in
   match item with
-  | Value {docstring; signature; name; linkables} ->
+  | Value {id; docstring; signature; name; linkables} ->
     stringifyObject ~startOnNewline:true ~indentation
       [
+        ("id", Some (wrapInQuotes id));
         ("kind", Some (wrapInQuotes "value"));
         ("name", Some (name |> Json.escape |> wrapInQuotes));
         ( "signature",
@@ -171,9 +193,10 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) =
             (stringifyLinkables ~originalEnv ~indentation:(indentation + 1)
                linkables) );
       ]
-  | Type {docstring; signature; name; detail; linkables} ->
+  | Type {id; docstring; signature; name; detail; linkables} ->
     stringifyObject ~startOnNewline:true ~indentation
       [
+        ("id", Some (wrapInQuotes id));
         ("kind", Some (wrapInQuotes "type"));
         ("name", Some (name |> Json.escape |> wrapInQuotes));
         ("signature", Some (signature |> Json.escape |> wrapInQuotes));
@@ -191,6 +214,7 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) =
   | Module m ->
     stringifyObject ~startOnNewline:true ~indentation
       [
+        ("id", Some (wrapInQuotes m.id));
         ("kind", Some (wrapInQuotes "module"));
         ( "item",
           Some
@@ -214,6 +238,9 @@ and stringifyDocsForModule ?(indentation = 0) ~originalEnv (d : docsForModule) =
 
 exception Invalid_file_type
 
+let makeId modulePath ~identifier =
+  identifier :: modulePath |> List.rev |> SharedTypes.ident
+
 let extractDocs ~path ~debug =
   if debug then Printf.printf "extracting docs for %s\n" path;
   if
@@ -241,8 +268,10 @@ let extractDocs ~path ~debug =
     let structure = file.structure in
     let open SharedTypes in
     let env = QueryEnv.fromFile file in
-    let rec extractDocs (structure : Module.structure) =
+    let rec extractDocs ?(modulePath = [env.file.moduleName])
+        (structure : Module.structure) =
       {
+        id = modulePath |> ident;
         docstring = structure.docstring |> List.map String.trim;
         name = structure.name;
         items =
@@ -253,6 +282,7 @@ let extractDocs ~path ~debug =
                    Some
                      (Value
                         {
+                          id = modulePath |> makeId ~identifier:item.name;
                           docstring = item.docstring |> List.map String.trim;
                           signature =
                             "let " ^ item.name ^ ": " ^ Shared.typeToString typ
@@ -265,6 +295,7 @@ let extractDocs ~path ~debug =
                    Some
                      (Type
                         {
+                          id = modulePath |> makeId ~identifier:item.name;
                           linkables =
                             Typ typ |> Linkables.findLinkables ~env ~full;
                           docstring = item.docstring |> List.map String.trim;
@@ -285,7 +316,12 @@ let extractDocs ~path ~debug =
                                      fieldDocs =
                                        fields
                                        |> List.map (fun (field : field) ->
-                                              (field.fname.txt, field.docstring));
+                                              {
+                                                fieldName = field.fname.txt;
+                                                docstrings = field.docstring;
+                                                signature =
+                                                  Shared.typeToString field.typ;
+                                              });
                                    })
                             | Some (Tvariant {constructors}) ->
                               Some
@@ -294,16 +330,27 @@ let extractDocs ~path ~debug =
                                      constructorDocs =
                                        constructors
                                        |> List.map (fun (c : Constructor.t) ->
-                                              (c.cname.txt, c.docstring));
+                                              {
+                                                constructorName = c.cname.txt;
+                                                docstrings = c.docstring;
+                                                signature =
+                                                  CompletionBackEnd
+                                                  .showConstructor c;
+                                              });
                                    })
                             | _ -> None);
                         })
                  | Module (Structure m) ->
                    (* module Whatever = {} in res or module Whatever: {} in resi. *)
-                   Some (Module (extractDocs m))
+                   Some
+                     (Module (extractDocs ~modulePath:(m.name :: modulePath) m))
                  | Module (Constraint (Structure _impl, Structure interface)) ->
                    (* module Whatever: { <interface> } = { <impl> }. Prefer the interface. *)
-                   Some (Module (extractDocs interface))
+                   Some
+                     (Module
+                        (extractDocs
+                           ~modulePath:(interface.name :: modulePath)
+                           interface))
                  | _ -> None);
       }
     in
diff --git a/analysis/tests/src/expected/DocExtraction2.res.txt b/analysis/tests/src/expected/DocExtraction2.res.txt
@@ -7,13 +7,15 @@ preferring found resi file for impl: src/DocExtraction2.resi
   "docstrings": ["Module level doc here."],
   "items": [
   {
+    "id": "DocExtraction2.t",
     "kind": "type",
     "name": "t",
     "signature": "type t",
     "docstrings": ["Type t is pretty cool."],
     "linkables": []
   }, 
   {
+    "id": "DocExtraction2.make",
     "kind": "value",
     "name": "make",
     "signature": "let make: unit => t",
@@ -25,20 +27,23 @@ preferring found resi file for impl: src/DocExtraction2.resi
       }]
   }, 
   {
+    "id": "InnerModule.DocExtraction2",
     "kind": "module",
     "item": 
     {
       "name": "InnerModule",
       "docstrings": [],
       "items": [
       {
+        "id": "DocExtraction2.InnerModule.t",
         "kind": "type",
         "name": "t",
         "signature": "type t",
         "docstrings": ["This type is also t."],
         "linkables": []
       }, 
       {
+        "id": "DocExtraction2.InnerModule.make",
         "kind": "value",
         "name": "make",
         "signature": "let make: unit => t",
diff --git a/analysis/tests/src/expected/DocExtraction2.resi.txt b/analysis/tests/src/expected/DocExtraction2.resi.txt
@@ -6,13 +6,15 @@ extracting docs for src/DocExtraction2.resi
   "docstrings": ["Module level doc here."],
   "items": [
   {
+    "id": "DocExtraction2.t",
     "kind": "type",
     "name": "t",
     "signature": "type t",
     "docstrings": ["Type t is pretty cool."],
     "linkables": []
   }, 
   {
+    "id": "DocExtraction2.make",
     "kind": "value",
     "name": "make",
     "signature": "let make: unit => t",
@@ -24,20 +26,23 @@ extracting docs for src/DocExtraction2.resi
       }]
   }, 
   {
+    "id": "InnerModule.DocExtraction2",
     "kind": "module",
     "item": 
     {
       "name": "InnerModule",
       "docstrings": [],
       "items": [
       {
+        "id": "DocExtraction2.InnerModule.t",
         "kind": "type",
         "name": "t",
         "signature": "type t",
         "docstrings": ["This type is also t."],
         "linkables": []
       }, 
       {
+        "id": "DocExtraction2.InnerModule.make",
         "kind": "value",
         "name": "make",
         "signature": "let make: unit => t",
diff --git a/analysis/tests/src/expected/DocExtractionRes.res.txt b/analysis/tests/src/expected/DocExtractionRes.res.txt
