support inline record fields in doc extraction

zth · zth · commit 6e4e49e343fa · 2024-01-11T08:26:34.000+01:00
diff --git a/analysis/src/CompletionBackEnd.ml b/analysis/src/CompletionBackEnd.ml
@@ -3,7 +3,18 @@ open SharedTypes
 let showConstructor {Constructor.cname = {txt}; args; res} =
   txt
   ^ (match args with
-    | Args [] | InlineRecord _ -> ""
+    | Args [] -> ""
+    | InlineRecord fields ->
+      "({"
+      ^ (fields
+        |> List.map (fun (field : field) ->
+               Printf.sprintf "%s%s: %s" field.fname.txt
+                 (if field.optional then "?" else "")
+                 (Shared.typeToString
+                    (if field.optional then Utils.unwrapIfOption field.typ
+                     else field.typ)))
+        |> String.concat ", ")
+      ^ "})"
     | Args args ->
       "("
       ^ (args
diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml
@@ -11,6 +11,7 @@ type constructorDoc = {
   docstrings: string list;
   signature: string;
   deprecated: string option;
+  inlineRecordFields: fieldDoc list option;
 }
 
 type docItemDetail =
@@ -54,6 +55,20 @@ let stringifyDocstrings docstrings =
   |> List.map (fun docstring -> docstring |> String.trim |> wrapInQuotes)
   |> array
 
+let stringifyFieldDoc ~indentation (fieldDoc : fieldDoc) =
+  let open Protocol in
+  stringifyObject ~indentation:(indentation + 1)
+    [
+      ("name", Some (wrapInQuotes fieldDoc.fieldName));
+      ( "deprecated",
+        match fieldDoc.deprecated with
+        | Some d -> Some (wrapInQuotes d)
+        | None -> None );
+      ("optional", Some (string_of_bool fieldDoc.optional));
+      ("docstrings", Some (stringifyDocstrings fieldDoc.docstrings));
+      ("signature", Some (wrapInQuotes fieldDoc.signature));
+    ]
+
 let stringifyDetail ?(indentation = 0) (detail : docItemDetail) =
   let open Protocol in
   match detail with
@@ -62,22 +77,8 @@ let stringifyDetail ?(indentation = 0) (detail : docItemDetail) =
       [
         ("kind", Some (wrapInQuotes "record"));
         ( "items",
-          Some
-            (fieldDocs
-            |> List.map (fun fieldDoc ->
-                   stringifyObject ~indentation:(indentation + 1)
-                     [
-                       ("name", Some (wrapInQuotes fieldDoc.fieldName));
-                       ( "deprecated",
-                         match fieldDoc.deprecated with
-                         | Some d -> Some (wrapInQuotes d)
-                         | None -> None );
-                       ("optional", Some (string_of_bool fieldDoc.optional));
-                       ( "docstrings",
-                         Some (stringifyDocstrings fieldDoc.docstrings) );
-                       ("signature", Some (wrapInQuotes fieldDoc.signature));
-                     ])
-            |> array) );
+          Some (fieldDocs |> List.map (stringifyFieldDoc ~indentation) |> array)
+        );
       ]
   | Variant {constructorDocs} ->
     stringifyObject ~startOnNewline:true ~indentation
@@ -100,6 +101,16 @@ let stringifyDetail ?(indentation = 0) (detail : docItemDetail) =
                          Some (stringifyDocstrings constructorDoc.docstrings) );
                        ( "signature",
                          Some (wrapInQuotes constructorDoc.signature) );
+                       ( "inlineRecordFields",
+                         match constructorDoc.inlineRecordFields with
+                         | None -> None
+                         | Some fieldDocs ->
+                           Some
+                             (fieldDocs
+                             |> List.map
+                                  (stringifyFieldDoc
+                                     ~indentation:(indentation + 1))
+                             |> array) );
                      ])
             |> array) );
       ]
@@ -185,24 +196,20 @@ and stringifyDocsForModule ?(indentation = 0) ~originalEnv (d : docsForModule) =
           |> array) );
     ]
 
+let fieldToFieldDoc (field : SharedTypes.field) : fieldDoc =
+  {
+    fieldName = field.fname.txt;
+    docstrings = field.docstring;
+    optional = field.optional;
+    signature = Shared.typeToString field.typ;
+    deprecated = field.deprecated;
+  }
+
 let typeDetail typ ~env ~full =
   let open SharedTypes in
   match TypeUtils.extractTypeFromResolvedType ~env ~full typ with
   | Some (Trecord {fields}) ->
-    Some
-      (Record
-         {
-           fieldDocs =
-             fields
-             |> List.map (fun (field : field) ->
-                    {
-                      fieldName = field.fname.txt;
-                      docstrings = field.docstring;
-                      optional = field.optional;
-                      signature = Shared.typeToString field.typ;
-                      deprecated = field.deprecated;
-                    });
-         })
+    Some (Record {fieldDocs = fields |> List.map fieldToFieldDoc})
   | Some (Tvariant {constructors}) ->
     Some
       (Variant
@@ -215,6 +222,11 @@ let typeDetail typ ~env ~full =
                       docstrings = c.docstring;
                       signature = CompletionBackEnd.showConstructor c;
                       deprecated = c.deprecated;
+                      inlineRecordFields =
+                        (match c.args with
+                        | InlineRecord fields ->
+                          Some (fields |> List.map fieldToFieldDoc)
+                        | _ -> None);
                     });
          })
   | _ -> None
diff --git a/analysis/tests/src/DocExtractionRes.res b/analysis/tests/src/DocExtractionRes.res
@@ -49,7 +49,12 @@ module AnotherModule = {
   let isGoodStatus = (status: SomeInnerModule.status) => status == Stopped
 
   /** Trying how it looks with an inline record in a variant. */
-  type someVariantWithInlineRecords = | /** This has inline records...*/ SomeStuff({offline: bool})
+  type someVariantWithInlineRecords =
+    | /** This has inline records...*/
+    SomeStuff({
+        offline: bool,
+        /** Is the user online? */ online?: bool,
+      })
 
   open ReactDOM
 
diff --git a/analysis/tests/src/expected/DocExtractionRes.res.txt b/analysis/tests/src/expected/DocExtractionRes.res.txt
@@ -125,7 +125,7 @@ extracting docs for src/DocExtractionRes.res
       "id": "DocExtractionRes.AnotherModule.someVariantWithInlineRecords",
       "kind": "type",
       "name": "someVariantWithInlineRecords",
-      "signature": "type someVariantWithInlineRecords =\n  | SomeStuff({offline: bool})",
+      "signature": "type someVariantWithInlineRecords =\n  | SomeStuff({offline: bool, online?: bool})",
       "docstrings": ["Trying how it looks with an inline record in a variant."],
       "detail": 
       {
@@ -134,7 +134,18 @@ extracting docs for src/DocExtractionRes.res
         {
           "name": "SomeStuff",
           "docstrings": ["This has inline records..."],
-          "signature": "SomeStuff"
+          "signature": "SomeStuff({offline: bool, online?: bool})",
+          "inlineRecordFields": [{
+            "name": "offline",
+            "optional": false,
+            "docstrings": [],
+            "signature": "bool"
+          }, {
+            "name": "online",
+            "optional": true,
+            "docstrings": ["Is the user online?"],
+            "signature": "option<bool>"
+          }]
         }]
       }
     }, 
diff --git a/tools/CHANGELOG.md b/tools/CHANGELOG.md
@@ -14,6 +14,7 @@
 
 #### :bug: Bug Fix
 
+- Support inline record fields in constructors.
 - Fix docstrings for module alias. Get internal docstrings of module file. https://github.com/rescript-lang/rescript-vscode/pull/878
 - Fix extracted docs of types include escaped linebreaks in signature. https://github.com/rescript-lang/rescript-vscode/pull/891
 
diff --git a/tools/src/Tools_Docgen.res b/tools/src/Tools_Docgen.res
@@ -11,6 +11,7 @@ type constructor = {
   docstrings: array<string>,
   signature: string,
   deprecated?: string,
+  inlineRecordFields?: array<field>,
 }
 
 @tag("kind")
@@ -54,159 +55,6 @@ type rec item =
       items: array<item>,
     })
 
-let decodeDocstrings = item => {
-  open Js.Json
-  switch item->Js.Dict.get("docstrings") {
-  | Some(Array(arr)) =>
-    arr->Js.Array2.map(s =>
-      switch s {
-      | String(s) => s
-      | _ => assert(false)
-      }
-    )
-  | _ => []
-  }
-}
-
-let decodeStringByField = (item, field) => {
-  open Js.Json
-  switch item->Js.Dict.get(field) {
-  | Some(String(s)) => s
-  | _ => assert(false)
-  }
-}
-
-let decodeDepreacted = item => {
-  open Js.Json
-  switch item->Js.Dict.get("deprecated") {
-  | Some(String(s)) => Some(s)
-  | _ => None
-  }
-}
-
-let decodeRecordFields = fields => {
-  open Js.Json
-  let items = fields->Js.Array2.map(field => {
-    switch field {
-    | Object(doc) => {
-        let name = doc->decodeStringByField("name")
-        let docstrings = doc->decodeDocstrings
-        let signature = doc->decodeStringByField("signature")
-        let deprecated = doc->decodeDepreacted
-        let optional = switch Js.Dict.get(doc, "optional") {
-        | Some(Boolean(bool)) => bool
-        | _ => assert(false)
-        }
-
-        {name, docstrings, signature, optional, ?deprecated}
-      }
-
-    | _ => assert(false)
-    }
-  })
-  Record({items: items})
-}
-
-let decodeConstructorFields = fields => {
-  open Js.Json
-  let items = fields->Js.Array2.map(field => {
-    switch field {
-    | Object(doc) => {
-        let name = doc->decodeStringByField("name")
-        let docstrings = doc->decodeDocstrings
-        let signature = doc->decodeStringByField("signature")
-        let deprecated = doc->decodeDepreacted
-
-        {name, docstrings, signature, ?deprecated}
-      }
-
-    | _ => assert(false)
-    }
-  })
-  Variant({items: items})
-}
-
-let decodeDetail = detail => {
-  open Js.Json
-
-  switch detail {
-  | Object(detail) =>
-    switch (detail->Js.Dict.get("kind"), detail->Js.Dict.get("items")) {
-    | (Some(String(kind)), Some(Array(items))) =>
-      switch kind {
-      | "record" => decodeRecordFields(items)
-      | "variant" => decodeConstructorFields(items)
-      | _ => assert(false)
-      }
-    | _ => assert(false)
-    }
-
-  | _ => assert(false)
-  }
-}
-
-let rec decodeValue = item => {
-  let id = item->decodeStringByField("id")
-  let signature = item->decodeStringByField("signature")
-  let name = item->decodeStringByField("name")
-  let deprecated = item->decodeDepreacted
-  let docstrings = item->decodeDocstrings
-  Value({id, docstrings, signature, name, ?deprecated})
-}
-and decodeType = item => {
-  let id = item->decodeStringByField("id")
-  let signature = item->decodeStringByField("signature")
-  let name = item->decodeStringByField("name")
-  let deprecated = item->decodeDepreacted
-  let docstrings = item->decodeDocstrings
-  let detail = switch item->Js_dict.get("detail") {
-  | Some(field) => decodeDetail(field)->Some
-  | None => None
-  }
-  Type({id, docstrings, signature, name, ?deprecated, ?detail})
-}
-and decodeModuleAlias = item => {
-  open Js.Json
-  let id = item->decodeStringByField("id")
-  let name = item->decodeStringByField("name")
-  let docstrings = item->decodeDocstrings
-  let items = switch Js.Dict.get(item, "items") {
-  | Some(Array(items)) => items->Js.Array2.map(item => decodeItem(item))
-  | _ => assert(false)
-  }
-  ModuleAlias({id, items, name, docstrings})
-}
-and decodeModule = item => {
-  open Js.Json
-  let id = item->decodeStringByField("id")
-  let name = item->decodeStringByField("name")
-  let deprecated = item->decodeDepreacted
-  let docstrings = item->decodeDocstrings
-  let items = switch Js.Dict.get(item, "items") {
-  | Some(Array(items)) => items->Js.Array2.map(item => decodeItem(item))
-  | _ => assert(false)
-  }
-  Module({id, name, docstrings, ?deprecated, items})
-}
-and decodeItem = item => {
-  open Js.Json
-  switch item {
-  | Object(value) =>
-    switch Js.Dict.get(value, "kind") {
-    | Some(String(kind)) =>
-      switch kind {
-      | "type" => decodeType(value)
-      | "value" => decodeValue(value)
-      | "module" => decodeModule(value)
-      | "moduleAlias" => decodeModuleAlias(value)
-      | _ => assert(false)
-      }
-    | _ => assert(false)
-    }
-  | _ => assert(false)
-  }
-}
-
 type doc = {
   name: string,
   deprecated: option<string>,
@@ -217,22 +65,4 @@ type doc = {
 /**
 `decodeFromJson(json)` parse JSON generated from `restool doc` command
 */
-let decodeFromJson = json => {
-  open Js.Json
-
-  switch json {
-  | Object(mod) => {
-      let name = mod->decodeStringByField("name")
-      let deprecated = mod->decodeDepreacted
-      let docstrings = mod->decodeDocstrings
-      let items = switch Js.Dict.get(mod, "items") {
-      | Some(Array(items)) => items->Js.Array2.map(item => decodeItem(item))
-      | _ => assert(false)
-      }
-
-      {name, deprecated, docstrings, items}
-    }
-
-  | _ => assert(false)
-  }
-}
+external decodeFromJson: Js.Json.t => doc = "%identity"
diff --git a/tools/src/Tools_Docgen.resi b/tools/src/Tools_Docgen.resi
@@ -10,6 +10,7 @@ type constructor = {
   docstrings: array<string>,
   signature: string,
   deprecated?: string,
+  inlineRecordFields?: array<field>,
 }
 @tag("kind")
 type detail =
@@ -54,9 +55,4 @@ type rec item =
 
 type doc = {name: string, deprecated: option<string>, docstrings: array<string>, items: array<item>}
 
-let decodeValue: Js.Dict.t<Js.Json.t> => item
-let decodeType: Js.Dict.t<Js.Json.t> => item
-let decodeModule: Js.Dict.t<Js.Json.t> => item
-let decodeModuleAlias: Js.Dict.t<Js.Json.t> => item
-let decodeItem: Js.Json.t => item
 let decodeFromJson: Js.Json.t => doc
