prefer resi file when available, and prefer module signature vs impl

Author: zth

analysis/src/DocExtraction.ml

@@ -212,21 +212,42 @@ and stringifyDocsForModule ?(indentation = 0) ~originalEnv (d : docsForModule) =
           |> array) );
     ]
 
+exception Invalid_file_type
+
 let extractDocs ~path ~debug =
   if debug then Printf.printf "extracting docs for %s\n" path;
+  if
+    FindFiles.isImplementation path = false
+    && FindFiles.isInterface path = false
+  then raise Invalid_file_type;
+  let path =
+    if FindFiles.isImplementation path then
+      let pathAsResi =
+        (path |> Filename.dirname) ^ "/"
+        ^ (path |> Filename.basename |> Filename.chop_extension)
+        ^ ".resi"
+      in
+      if Sys.file_exists pathAsResi then (
+        if debug then
+          Printf.printf "preferring found resi file for impl: %s\n" pathAsResi;
+        pathAsResi)
+      else path
+    else path
+  in
   match Cmt.loadFullCmtFromPath ~path with
   | None -> ()
   | Some full ->
     let file = full.file in
     let structure = file.structure in
-    let env = SharedTypes.QueryEnv.fromFile file in
-    let rec extractDocs (structure : SharedTypes.Module.structure) =
+    let open SharedTypes in
+    let env = QueryEnv.fromFile file in
+    let rec extractDocs (structure : Module.structure) =
       {
         docstring = structure.docstring |> List.map String.trim;
         name = structure.name;
         items =
           structure.items
-          |> List.filter_map (fun (item : SharedTypes.Module.item) ->
+          |> List.filter_map (fun (item : Module.item) ->
                  match item.kind with
                  | Value typ ->
                    Some
@@ -263,8 +284,7 @@ let extractDocs ~path ~debug =
                                    {
                                      fieldDocs =
                                        fields
-                                       |> List.map
-                                            (fun (field : SharedTypes.field) ->
+                                       |> List.map (fun (field : field) ->
                                               (field.fname.txt, field.docstring));
                                    })
                             | Some (Tvariant {constructors}) ->
@@ -273,13 +293,17 @@ let extractDocs ~path ~debug =
                                    {
                                      constructorDocs =
                                        constructors
-                                       |> List.map
-                                            (fun (c : SharedTypes.Constructor.t)
-                                            -> (c.cname.txt, c.docstring));
+                                       |> List.map (fun (c : Constructor.t) ->
+                                              (c.cname.txt, c.docstring));
                                    })
                             | _ -> None);
                         })
-                 | Module (Structure m) -> Some (Module (extractDocs m))
+                 | Module (Structure m) ->
+                   (* module Whatever = {} in res or module Whatever: {} in resi. *)
+                   Some (Module (extractDocs m))
+                 | Module (Constraint (Structure _impl, Structure interface)) ->
+                   (* module Whatever: { <interface> } = { <impl> }. Prefer the interface. *)
+                   Some (Module (extractDocs interface))
                  | _ -> None);
       }
     in

analysis/tests/src/DocExtraction2.res

@@ -0,0 +1,12 @@
+type t = string
+
+let getStr = () => "123"
+
+let make = getStr
+
+module InnerModule = {
+  type t = unit
+  let make = () => ()
+}
+
+// ^dex

analysis/tests/src/DocExtraction2.resi

@@ -0,0 +1,19 @@
+/*** Module level doc here.*/
+
+/** Type t is pretty cool.*/
+type t
+
+/** Makerz of stuffz. */
+let make: unit => t
+
+module InnerModule: {
+  /*** This inner module is nice...*/
+
+  /** This type is also t. */
+  type t
+
+  /** Maker of tea.*/
+  let make: unit => t
+}
+
+// ^dex

analysis/tests/src/DocExtractionRes.res

@@ -51,4 +51,38 @@ module AnotherModule = {
   type domRoot = unit => Client.Root.t
 }
 
+module ModuleWithThingsThatShouldNotBeExported: {
+  /*** BROKEN: This docstring isn't picked up Doesn't seem to be parsed at all, no attributes found.*/
+
+  /** The type t is stuff. */
+  type t
+
+  /** The maker of stuff!*/
+  let make: unit => t
+} = {
+  /*** Mighty fine module here too!*/
+  type t = string
+  type x = int
+  type f = bool
+
+  let m1 = (x: x) => {
+    x + 1
+  }
+
+  let m2 = (f: f) =>
+    if f {
+      true
+    } else {
+      false
+    }
+
+  let make = () => {
+    if m2(true) && m1(1) > 2 {
+      "1"
+    } else {
+      "2"
+    }
+  }
+}
+
 // ^dex

analysis/tests/src/expected/DocExtraction2.res.txt

@@ -0,0 +1,55 @@
+Documentation extraction src/DocExtraction2.res
+extracting docs for src/DocExtraction2.res
+preferring found resi file for impl: src/DocExtraction2.resi
+
+{
+  "name": "DocExtraction2",
+  "docstrings": ["Module level doc here."],
+  "items": [
+  {
+    "kind": "type",
+    "name": "t",
+    "signature": "type t",
+    "docstrings": ["Type t is pretty cool."],
+    "linkables": []
+  }, 
+  {
+    "kind": "value",
+    "name": "make",
+    "signature": "let make: unit => t",
+    "docstrings": ["Makerz of stuffz."],
+    "linkables": [{
+        "path": "t",
+        "moduleName": "DocExtraction2",
+        "external": false
+      }]
+  }, 
+  {
+    "kind": "module",
+    "item": 
+    {
+      "name": "InnerModule",
+      "docstrings": [],
+      "items": [
+      {
+        "kind": "type",
+        "name": "t",
+        "signature": "type t",
+        "docstrings": ["This type is also t."],
+        "linkables": []
+      }, 
+      {
+        "kind": "value",
+        "name": "make",
+        "signature": "let make: unit => t",
+        "docstrings": ["Maker of tea."],
+        "linkables": [{
+            "path": "t",
+            "moduleName": "DocExtraction2",
+            "external": false
+          }]
+      }]
+    }
+  }]
+}
+

analysis/tests/src/expected/DocExtraction2.resi.txt

@@ -0,0 +1,54 @@
+Documentation extraction src/DocExtraction2.resi
+extracting docs for src/DocExtraction2.resi
+
+{
+  "name": "DocExtraction2",
+  "docstrings": ["Module level doc here."],
+  "items": [
+  {
+    "kind": "type",
+    "name": "t",
+    "signature": "type t",
+    "docstrings": ["Type t is pretty cool."],
+    "linkables": []
+  }, 
+  {
+    "kind": "value",
+    "name": "make",
+    "signature": "let make: unit => t",
+    "docstrings": ["Makerz of stuffz."],
+    "linkables": [{
+        "path": "t",
+        "moduleName": "DocExtraction2",
+        "external": false
+      }]
+  }, 
+  {
+    "kind": "module",
+    "item": 
+    {
+      "name": "InnerModule",
+      "docstrings": [],
+      "items": [
+      {
+        "kind": "type",
+        "name": "t",
+        "signature": "type t",
+        "docstrings": ["This type is also t."],
+        "linkables": []
+      }, 
+      {
+        "kind": "value",
+        "name": "make",
+        "signature": "let make: unit => t",
+        "docstrings": ["Maker of tea."],
+        "linkables": [{
+            "path": "t",
+            "moduleName": "DocExtraction2",
+            "external": false
+          }]
+      }]
+    }
+  }]
+}
+

analysis/tests/src/expected/DocExtractionRes.res.txt

@@ -161,6 +161,33 @@ extracting docs for src/DocExtractionRes.res
           }]
       }]
     }
+  }, 
+  {
+    "kind": "module",
+    "item": 
+    {
+      "name": "ModuleWithThingsThatShouldNotBeExported",
+      "docstrings": [],
+      "items": [
+      {
+        "kind": "type",
+        "name": "t",
+        "signature": "type t",
+        "docstrings": ["The type t is stuff."],
+        "linkables": []
+      }, 
+      {
+        "kind": "value",
+        "name": "make",
+        "signature": "let make: unit => t",
+        "docstrings": ["The maker of stuff!"],
+        "linkables": [{
+            "path": "t",
+            "moduleName": "DocExtractionRes",
+            "external": false
+          }]
+      }]
+    }
   }]
 }