From d73978e8909bac02b6800ed0acd1f013101d5403 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sun, 28 Jan 2024 22:24:51 -0300 Subject: [PATCH 1/2] tools: add content for local module alias --- tools/src/tools.ml | 24 +++++++- .../src/expected/DocExtractionRes.res.json | 60 ++++++++++++++++++- 2 files changed, 81 insertions(+), 3 deletions(-) diff --git a/tools/src/tools.ml b/tools/src/tools.ml index 0db7ee50b..72e429ffa 100644 --- a/tools/src/tools.ml +++ b/tools/src/tools.ml @@ -390,7 +390,29 @@ let extractDocs ~entryPointFile ~debug = ProcessCmt.fileForModule ~package:full.package aliasToModule with - | None -> ([], []) + | None -> ( + let localModuleAliasDocs = + match + Exported.find env.exported Module aliasToModule + with + | None -> None + | Some stamp -> ( + match + SharedTypes.Stamps.findModule full.file.stamps + stamp + with + | None -> None + | Some {item} -> ( + match item with + | Structure struc -> + Some + (extractDocsForModule ~modulePath:[id] + struc) + | _ -> None)) + in + match localModuleAliasDocs with + | Some {items; docstring} -> (items, docstring) + | None -> ([], [])) | Some file -> let docs = extractDocsForModule ~modulePath:[id] diff --git a/tools/tests/src/expected/DocExtractionRes.res.json b/tools/tests/src/expected/DocExtractionRes.res.json index a07ada95f..331c780bf 100644 --- a/tools/tests/src/expected/DocExtractionRes.res.json +++ b/tools/tests/src/expected/DocExtractionRes.res.json @@ -154,13 +154,69 @@ "id": "DocExtractionRes.LinkedModule", "kind": "moduleAlias", "name": "LinkedModule", - "docstrings": ["This links another module. Neat."], + "docstrings": ["This links another module. Neat.", "Another module level docstring here."], "source": { "filepath": "src/DocExtractionRes.res", "line": 43, "col": 10 }, - "items": [] + "items": [ + { + "id": "DocExtractionRes.LinkedModule.status", + "kind": "type", + "name": "status", + "signature": "type status = Started(t) | Stopped | Idle", + "docstrings": [], + "source": { + "filepath": "src/DocExtractionRes.res", + "line": 30, + "col": 3 + }, + "detail": + { + "kind": "variant", + "items": [ + { + "name": "Started", + "docstrings": ["If this is started or not"], + "signature": "Started(t)" + }, + { + "name": "Stopped", + "docstrings": ["Stopped?"], + "signature": "Stopped" + }, + { + "name": "Idle", + "docstrings": ["Now idle."], + "signature": "Idle" + }] + } + }, + { + "id": "DocExtractionRes.LinkedModule.validInputs", + "kind": "type", + "name": "validInputs", + "signature": "type validInputs = [\n | #\"needs-escaping\"\n | #something\n | #status(status)\n | #withPayload(int)\n]", + "docstrings": ["These are all the valid inputs."], + "source": { + "filepath": "src/DocExtractionRes.res", + "line": 34, + "col": 3 + } + }, + { + "id": "DocExtractionRes.LinkedModule.callback", + "kind": "type", + "name": "callback", + "signature": "type callback = (. t, ~status: status) => unit", + "docstrings": [], + "source": { + "filepath": "src/DocExtractionRes.res", + "line": 36, + "col": 3 + } + }] }, { "id": "DocExtractionRes.AnotherModule.callback", From e2d2770c6f26941c4b0511fa7f08809165ecd5d5 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sat, 3 Feb 2024 18:18:21 -0300 Subject: [PATCH 2/2] dont print ghost location --- tools/src/tools.ml | 73 +++++--- tools/tests/src/Aliases.res | 9 + tools/tests/src/expected/Aliases.res.json | 159 ++++++++++++++++++ .../src/expected/DocExtractionRes.res.json | 2 +- 4 files changed, 214 insertions(+), 29 deletions(-) create mode 100644 tools/tests/src/Aliases.res create mode 100644 tools/tests/src/expected/Aliases.res.json diff --git a/tools/src/tools.ml b/tools/src/tools.ml index 72e429ffa..9570a1885 100644 --- a/tools/src/tools.ml +++ b/tools/src/tools.ml @@ -31,7 +31,7 @@ type docItem = signature: string; name: string; deprecated: string option; - source: source; + source: source option; } | Type of { id: string; @@ -40,7 +40,7 @@ type docItem = name: string; deprecated: string option; detail: docItemDetail option; - source: source; + source: source option; (** Additional documentation for constructors and record fields, if available. *) } | Module of docsForModule @@ -48,7 +48,7 @@ type docItem = id: string; docstring: string list; name: string; - source: source; + source: source option; items: docItem list; } and docsForModule = { @@ -56,7 +56,7 @@ and docsForModule = { docstring: string list; deprecated: string option; name: string; - source: source; + source: source option; items: docItem list; } @@ -163,7 +163,10 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) = | None -> None ); ("signature", Some (signature |> String.trim |> wrapInQuotes)); ("docstrings", Some (stringifyDocstrings docstring)); - ("source", Some (stringifySource ~indentation:(indentation + 1) source)); + ( "source", + match source with + | Some s -> Some (stringifySource ~indentation:(indentation + 1) s) + | None -> None ); ] | Type {id; docstring; signature; name; deprecated; detail; source} -> stringifyObject ~startOnNewline:true ~indentation @@ -177,7 +180,10 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) = | None -> None ); ("signature", Some (signature |> wrapInQuotes)); ("docstrings", Some (stringifyDocstrings docstring)); - ("source", Some (stringifySource ~indentation:(indentation + 1) source)); + ( "source", + match source with + | Some s -> Some (stringifySource ~indentation:(indentation + 1) s) + | None -> None ); ( "detail", match detail with | None -> None @@ -196,7 +202,9 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) = | None -> None ); ("docstrings", Some (stringifyDocstrings m.docstring)); ( "source", - Some (stringifySource ~indentation:(indentation + 1) m.source) ); + match m.source with + | Some s -> Some (stringifySource ~indentation:(indentation + 1) s) + | None -> None ); ( "items", Some (m.items @@ -212,7 +220,9 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) = ("name", Some (wrapInQuotes m.name)); ("docstrings", Some (stringifyDocstrings m.docstring)); ( "source", - Some (stringifySource ~indentation:(indentation + 1) m.source) ); + match m.source with + | Some s -> Some (stringifySource ~indentation:(indentation + 1) s) + | None -> None ); ( "items", Some (m.items @@ -231,7 +241,10 @@ and stringifyDocsForModule ?(indentation = 0) ~originalEnv (d : docsForModule) = | Some d -> Some (wrapInQuotes d) | None -> None ); ("docstrings", Some (stringifyDocstrings d.docstring)); - ("source", Some (stringifySource ~indentation:(indentation + 1) d.source)); + ( "source", + match d.source with + | Some s -> Some (stringifySource ~indentation:(indentation + 1) s) + | None -> None ); ( "items", Some (d.items @@ -280,14 +293,17 @@ let typeDetail typ ~env ~full = let makeId modulePath ~identifier = identifier :: modulePath |> List.rev |> SharedTypes.ident -let getSource ~rootPath ({loc_start} : Location.t) = - let line, col = Pos.ofLexing loc_start in - let filepath = - Files.relpath rootPath loc_start.pos_fname - |> Files.split Filename.dir_sep - |> String.concat "/" - in - {filepath; line = line + 1; col = col + 1} +let getSource ~rootPath ({loc_start; loc_ghost} : Location.t) = + match loc_ghost with + | true -> None + | false -> + let line, col = Pos.ofLexing loc_start in + let filepath = + Files.relpath rootPath loc_start.pos_fname + |> Files.split Filename.dir_sep + |> String.concat "/" + in + Some {filepath; line = line + 1; col = col + 1} let extractDocs ~entryPointFile ~debug = let path = @@ -337,17 +353,18 @@ let extractDocs ~entryPointFile ~debug = name = structure.name; deprecated = structure.deprecated; source = - { - filepath = - (match rootPath = "." with - | true -> file.uri |> Uri.toPath - | false -> - Files.relpath rootPath (file.uri |> Uri.toPath) - |> Files.split Filename.dir_sep - |> String.concat "/"); - line = 1; - col = 1; - }; + Some + { + filepath = + (match rootPath = "." with + | true -> file.uri |> Uri.toPath + | false -> + Files.relpath rootPath (file.uri |> Uri.toPath) + |> Files.split Filename.dir_sep + |> String.concat "/"); + line = 1; + col = 1; + }; items = structure.items |> List.filter_map (fun (item : Module.item) -> diff --git a/tools/tests/src/Aliases.res b/tools/tests/src/Aliases.res new file mode 100644 index 000000000..966dddb77 --- /dev/null +++ b/tools/tests/src/Aliases.res @@ -0,0 +1,9 @@ +@warning("-60") + +module Exn = Js.Exn + +module UtilsPromises = { + include Js.Promise2 + + module OldPromise = Js.Promise +} diff --git a/tools/tests/src/expected/Aliases.res.json b/tools/tests/src/expected/Aliases.res.json new file mode 100644 index 000000000..b06112071 --- /dev/null +++ b/tools/tests/src/expected/Aliases.res.json @@ -0,0 +1,159 @@ + +{ + "name": "Aliases", + "docstrings": [], + "source": { + "filepath": "src/Aliases.res", + "line": 1, + "col": 1 + }, + "items": [ + { + "id": "Aliases.Exn", + "kind": "moduleAlias", + "name": "Exn", + "docstrings": [], + "source": { + "filepath": "src/Aliases.res", + "line": 3, + "col": 8 + }, + "items": [] + }, + { + "id": "Aliases.UtilsPromises", + "name": "UtilsPromises", + "kind": "module", + "docstrings": [], + "source": { + "filepath": "src/Aliases.res", + "line": 5, + "col": 8 + }, + "items": [ + { + "id": "Aliases.UtilsPromises.t", + "kind": "type", + "name": "t", + "signature": "type t<'a> = promise<'a>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.error", + "kind": "type", + "name": "error", + "signature": "type error = Js_promise2.error", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.then", + "kind": "value", + "name": "then", + "signature": "let then: (promise<'a>, 'a => promise<'b>) => promise<'b>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.catch", + "kind": "value", + "name": "catch", + "signature": "let catch: (promise<'a>, error => promise<'a>) => promise<'a>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.make", + "kind": "value", + "name": "make", + "signature": "let make: (\n (~resolve: 'a => unit, ~reject: exn => unit) => unit,\n) => promise<'a>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.resolve", + "kind": "value", + "name": "resolve", + "signature": "let resolve: 'a => promise<'a>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.reject", + "kind": "value", + "name": "reject", + "signature": "let reject: exn => promise<'a>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.all", + "kind": "value", + "name": "all", + "signature": "let all: array> => promise>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.all2", + "kind": "value", + "name": "all2", + "signature": "let all2: ((promise<'a0>, promise<'a1>)) => promise<('a0, 'a1)>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.all3", + "kind": "value", + "name": "all3", + "signature": "let all3: (\n (promise<'a0>, promise<'a1>, promise<'a2>),\n) => promise<('a0, 'a1, 'a2)>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.all4", + "kind": "value", + "name": "all4", + "signature": "let all4: (\n (promise<'a0>, promise<'a1>, promise<'a2>, promise<'a3>),\n) => promise<('a0, 'a1, 'a2, 'a3)>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.all5", + "kind": "value", + "name": "all5", + "signature": "let all5: (\n (\n promise<'a0>,\n promise<'a1>,\n promise<'a2>,\n promise<'a3>,\n promise<'a4>,\n ),\n) => promise<('a0, 'a1, 'a2, 'a3, 'a4)>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.all6", + "kind": "value", + "name": "all6", + "signature": "let all6: (\n (\n promise<'a0>,\n promise<'a1>,\n promise<'a2>,\n promise<'a3>,\n promise<'a4>,\n promise<'a5>,\n ),\n) => promise<('a0, 'a1, 'a2, 'a3, 'a4, 'a5)>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.race", + "kind": "value", + "name": "race", + "signature": "let race: array> => promise<'a>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.unsafe_async", + "kind": "value", + "name": "unsafe_async", + "signature": "let unsafe_async: 'a => promise<'a>", + "docstrings": [] + }, + { + "id": "Aliases.UtilsPromises.unsafe_await", + "kind": "value", + "name": "unsafe_await", + "signature": "let unsafe_await: promise<'a> => 'a", + "docstrings": [] + }, + { + "id": "Aliases.OldPromise", + "kind": "moduleAlias", + "name": "OldPromise", + "docstrings": [], + "source": { + "filepath": "src/Aliases.res", + "line": 8, + "col": 10 + }, + "items": [] + }] + }] +} diff --git a/tools/tests/src/expected/DocExtractionRes.res.json b/tools/tests/src/expected/DocExtractionRes.res.json index 00badfde5..755d9cb1c 100644 --- a/tools/tests/src/expected/DocExtractionRes.res.json +++ b/tools/tests/src/expected/DocExtractionRes.res.json @@ -209,7 +209,7 @@ "id": "DocExtractionRes.LinkedModule.callback", "kind": "type", "name": "callback", - "signature": "type callback = (. t, ~status: status) => unit", + "signature": "type callback = (t, ~status: status) => unit", "docstrings": [], "source": { "filepath": "src/DocExtractionRes.res",