From b7683c89ca79bdd80c81441cffd4f1f6fd12ae24 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Thu, 27 Jul 2023 20:47:32 -0300 Subject: [PATCH 01/10] emit items from module alias --- analysis/src/DocExtraction.ml | 38 ++++++++++++++++++++++++----------- 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml index 202541ec5..7ee804fb7 100644 --- a/analysis/src/DocExtraction.ml +++ b/analysis/src/DocExtraction.ml @@ -6,13 +6,6 @@ type constructorDoc = { signature: string; } -type docsForModuleAlias = { - id: string; - docstring: string list; - name: string; - signature: string; -} - type docItemDetail = | Record of {fieldDocs: fieldDoc list} | Variant of {constructorDocs: constructorDoc list} @@ -32,7 +25,12 @@ type docItem = (** Additional documentation for constructors and record fields, if available. *) } | Module of docsForModule - | ModuleAlias of docsForModuleAlias + | ModuleAlias of { + id: string; + docstring: string list; + name: string; + items: docItem list; + } and docsForModule = { id: string; docstring: string list; @@ -137,9 +135,15 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) = stringifyObject ~startOnNewline:true ~indentation [ ("id", Some (wrapInQuotes m.id)); + ("name", Some (wrapInQuotes m.name)); ("kind", Some (wrapInQuotes "moduleAlias")); ("docstrings", Some (stringifyDocstrings m.docstring)); - ("signature", Some (m.signature |> Json.escape |> wrapInQuotes)); + ( "items", + Some + (m.items + |> List.map + (stringifyDocItem ~originalEnv ~indentation:(indentation + 1)) + |> array) ); ] and stringifyDocsForModule ?(indentation = 0) ~originalEnv (d : docsForModule) = @@ -257,14 +261,24 @@ let extractDocs ~path ~debug = (* module Whatever = OtherModule *) let aliasToModule = p |> pathIdentToString in let modulePath = aliasToModule :: modulePath in + let items = + match + ProcessCmt.fileForModule ~package:full.package + aliasToModule + with + | None -> [] + | Some file -> + let docs = + extractDocsForModule ~modulePath file.structure + in + docs.items + in Some (ModuleAlias { id = modulePath |> List.rev |> SharedTypes.ident; - signature = - Printf.sprintf "module %s = %s" item.name - aliasToModule; name = item.name; + items; docstring = item.docstring |> List.map String.trim; }) | Module (Structure m) -> From 37a5df70f66416dd3c0163587b461ae1b380c185 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Wed, 27 Sep 2023 23:22:13 -0300 Subject: [PATCH 02/10] add error msg --- analysis/src/DocExtraction.ml | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml index d914683fd..d97409cc0 100644 --- a/analysis/src/DocExtraction.ml +++ b/analysis/src/DocExtraction.ml @@ -229,8 +229,6 @@ let typeDetail typ ~env ~full = }) | _ -> None -exception Invalid_file_type - let makeId modulePath ~identifier = identifier :: modulePath |> List.rev |> SharedTypes.ident @@ -239,7 +237,10 @@ let extractDocs ~path ~debug = if FindFiles.isImplementation path = false && FindFiles.isInterface path = false - then raise Invalid_file_type; + then ( + Printf.printf "error: failed to read %s, expected an .res or .resi file\n" + path; + exit 1); let path = if FindFiles.isImplementation path then let pathAsResi = @@ -255,7 +256,10 @@ let extractDocs ~path ~debug = else path in match Cmt.loadFullCmtFromPath ~path with - | None -> () + | None -> + Printf.printf + "error: failed to generate doc for %s, try to build the project\n" path; + exit 1 | Some full -> let file = full.file in let structure = file.structure in From f7e94d3b0a4a28c02df3c2980cae56989ac37a13 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Wed, 27 Sep 2023 23:31:20 -0300 Subject: [PATCH 03/10] rename fields --- analysis/src/DocExtraction.ml | 8 +++---- .../src/expected/DocExtractionRes.res.txt | 21 ++++++++++--------- 2 files changed, 15 insertions(+), 14 deletions(-) diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml index d97409cc0..9134f06fe 100644 --- a/analysis/src/DocExtraction.ml +++ b/analysis/src/DocExtraction.ml @@ -70,13 +70,13 @@ let stringifyDetail ?(indentation = 0) (detail : docItemDetail) = stringifyObject ~startOnNewline:true ~indentation [ ("kind", Some (wrapInQuotes "record")); - ( "fieldDocs", + ( "items", Some (fieldDocs |> List.map (fun fieldDoc -> stringifyObject ~indentation:(indentation + 1) [ - ("fieldName", Some (wrapInQuotes fieldDoc.fieldName)); + ("name", Some (wrapInQuotes fieldDoc.fieldName)); ( "deprecated", match fieldDoc.deprecated with | Some d -> Some (wrapInQuotes d) @@ -92,14 +92,14 @@ let stringifyDetail ?(indentation = 0) (detail : docItemDetail) = stringifyObject ~startOnNewline:true ~indentation [ ("kind", Some (wrapInQuotes "variant")); - ( "constructorDocs", + ( "items", Some (constructorDocs |> List.map (fun constructorDoc -> stringifyObject ~startOnNewline:true ~indentation:(indentation + 1) [ - ( "constructorName", + ( "name", Some (wrapInQuotes constructorDoc.constructorName) ); ( "deprecated", match constructorDoc.deprecated with diff --git a/analysis/tests/src/expected/DocExtractionRes.res.txt b/analysis/tests/src/expected/DocExtractionRes.res.txt index 4a6edea83..07e9dbc9b 100644 --- a/analysis/tests/src/expected/DocExtractionRes.res.txt +++ b/analysis/tests/src/expected/DocExtractionRes.res.txt @@ -14,13 +14,13 @@ extracting docs for src/DocExtractionRes.res "detail": { "kind": "record", - "fieldDocs": [{ - "fieldName": "name", + "items": [{ + "name": "name", "optional": false, "docstrings": ["The name of the stuff."], "signature": "string" }, { - "fieldName": "online", + "name": "online", "optional": false, "docstrings": ["Whether stuff is online."], "signature": "bool" @@ -55,19 +55,19 @@ extracting docs for src/DocExtractionRes.res "detail": { "kind": "variant", - "constructorDocs": [ + "items": [ { - "constructorName": "Started", + "name": "Started", "docstrings": ["If this is started or not"], "signature": "Started(t)" }, { - "constructorName": "Stopped", + "name": "Stopped", "docstrings": ["Stopped?"], "signature": "Stopped" }, { - "constructorName": "Idle", + "name": "Idle", "docstrings": ["Now idle."], "signature": "Idle" }] @@ -95,10 +95,11 @@ extracting docs for src/DocExtractionRes.res "items": [ { "id": "DocExtractionRes.AnotherModule.SomeInnerModule", + "name": "LinkedModule", "kind": "moduleAlias", "name": "LinkedModule", "docstrings": ["This links another module. Neat."], - "signature": "module LinkedModule = SomeInnerModule" + "items": [] }, { "id": "DocExtractionRes.AnotherModule.callback", @@ -123,9 +124,9 @@ extracting docs for src/DocExtractionRes.res "detail": { "kind": "variant", - "constructorDocs": [ + "items": [ { - "constructorName": "SomeStuff", + "name": "SomeStuff", "docstrings": ["This has inline records..."], "signature": "SomeStuff" }] From 6756e0da5c119da28a46b0ec6f0c5a61ab85a4a5 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Fri, 29 Sep 2023 18:31:01 -0300 Subject: [PATCH 04/10] remove double name field --- analysis/src/DocExtraction.ml | 1 - analysis/tests/src/expected/DocExtractionRes.res.txt | 1 - 2 files changed, 2 deletions(-) diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml index 9134f06fe..51c2d2e4a 100644 --- a/analysis/src/DocExtraction.ml +++ b/analysis/src/DocExtraction.ml @@ -165,7 +165,6 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) = stringifyObject ~startOnNewline:true ~indentation [ ("id", Some (wrapInQuotes m.id)); - ("name", Some (wrapInQuotes m.name)); ("kind", Some (wrapInQuotes "moduleAlias")); ("name", Some (wrapInQuotes m.name)); ("docstrings", Some (stringifyDocstrings m.docstring)); diff --git a/analysis/tests/src/expected/DocExtractionRes.res.txt b/analysis/tests/src/expected/DocExtractionRes.res.txt index 07e9dbc9b..762212e28 100644 --- a/analysis/tests/src/expected/DocExtractionRes.res.txt +++ b/analysis/tests/src/expected/DocExtractionRes.res.txt @@ -95,7 +95,6 @@ extracting docs for src/DocExtractionRes.res "items": [ { "id": "DocExtractionRes.AnotherModule.SomeInnerModule", - "name": "LinkedModule", "kind": "moduleAlias", "name": "LinkedModule", "docstrings": ["This links another module. Neat."], From 4b3479b68a12d61baf490331eb9b86668ff21d54 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Fri, 29 Sep 2023 19:53:15 -0300 Subject: [PATCH 05/10] add ocaml.text attr --- analysis/src/ProcessAttributes.ml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analysis/src/ProcessAttributes.ml b/analysis/src/ProcessAttributes.ml index c610d1e79..60ba88c21 100644 --- a/analysis/src/ProcessAttributes.ml +++ b/analysis/src/ProcessAttributes.ml @@ -5,7 +5,7 @@ let rec findDocAttribute attributes = let open Parsetree in match attributes with | [] -> None - | ( {Asttypes.txt = "ocaml.doc" | "ns.doc" | "res.doc"}, + | ( {Asttypes.txt = "ocaml.doc" | "ocaml.text" | "ns.doc" | "res.doc"}, PStr [ { From 01631e971f7dbbd5018736fd3efd92e0b6cd3ffe Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Fri, 29 Sep 2023 21:48:00 -0300 Subject: [PATCH 06/10] search for all attrs --- analysis/src/ProcessCmt.ml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/analysis/src/ProcessCmt.ml b/analysis/src/ProcessCmt.ml index 6468fc83f..87fdba2b4 100644 --- a/analysis/src/ProcessCmt.ml +++ b/analysis/src/ProcessCmt.ml @@ -593,9 +593,11 @@ and forStructure ~name ~env strItems = strItems [] in let attributes = - match strItems with - | {str_desc = Tstr_attribute attribute} :: _ -> [attribute] - | _ -> [] + strItems + |> List.filter_map (fun (struc : Typedtree.structure_item) -> + match struc with + | {str_desc = Tstr_attribute attr} -> Some attr + | _ -> None) in let docstring = attrsToDocstring attributes in let deprecated = ProcessAttributes.findDeprecatedAttribute attributes in From e5937e09ec706db4a4295b4d52bd6072018d3919 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sat, 30 Sep 2023 17:49:33 -0300 Subject: [PATCH 07/10] fix id module --- analysis/src/DocExtraction.ml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml index 51c2d2e4a..4bf20425e 100644 --- a/analysis/src/DocExtraction.ml +++ b/analysis/src/DocExtraction.ml @@ -267,7 +267,7 @@ let extractDocs ~path ~debug = let rec extractDocsForModule ?(modulePath = [env.file.moduleName]) (structure : Module.structure) = { - id = modulePath |> ident; + id = modulePath |> List.rev |> ident; docstring = structure.docstring |> List.map String.trim; name = structure.name; deprecated = structure.deprecated; From 323758df26cac587325e71f77c19f1b541cb376b Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sat, 30 Sep 2023 17:51:20 -0300 Subject: [PATCH 08/10] update tests --- analysis/tests/src/expected/DocExtraction2.res.txt | 2 +- analysis/tests/src/expected/DocExtraction2.resi.txt | 2 +- analysis/tests/src/expected/DocExtractionRes.res.txt | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/analysis/tests/src/expected/DocExtraction2.res.txt b/analysis/tests/src/expected/DocExtraction2.res.txt index 4f7f4dbbd..7645cfac0 100644 --- a/analysis/tests/src/expected/DocExtraction2.res.txt +++ b/analysis/tests/src/expected/DocExtraction2.res.txt @@ -21,7 +21,7 @@ preferring found resi file for impl: src/DocExtraction2.resi "docstrings": ["Makerz of stuffz."] }, { - "id": "InnerModule.DocExtraction2", + "id": "DocExtraction2.InnerModule", "name": "InnerModule", "kind": "module", "items": [ diff --git a/analysis/tests/src/expected/DocExtraction2.resi.txt b/analysis/tests/src/expected/DocExtraction2.resi.txt index 923680e52..51d938f0c 100644 --- a/analysis/tests/src/expected/DocExtraction2.resi.txt +++ b/analysis/tests/src/expected/DocExtraction2.resi.txt @@ -20,7 +20,7 @@ extracting docs for src/DocExtraction2.resi "docstrings": ["Makerz of stuffz."] }, { - "id": "InnerModule.DocExtraction2", + "id": "DocExtraction2.InnerModule", "name": "InnerModule", "kind": "module", "items": [ diff --git a/analysis/tests/src/expected/DocExtractionRes.res.txt b/analysis/tests/src/expected/DocExtractionRes.res.txt index 762212e28..4ae808089 100644 --- a/analysis/tests/src/expected/DocExtractionRes.res.txt +++ b/analysis/tests/src/expected/DocExtractionRes.res.txt @@ -42,7 +42,7 @@ extracting docs for src/DocExtractionRes.res "docstrings": ["Stuff goes offline."] }, { - "id": "SomeInnerModule.DocExtractionRes", + "id": "DocExtractionRes.SomeInnerModule", "name": "SomeInnerModule", "kind": "module", "items": [ @@ -89,7 +89,7 @@ extracting docs for src/DocExtractionRes.res }] }, { - "id": "AnotherModule.DocExtractionRes", + "id": "DocExtractionRes.AnotherModule", "name": "AnotherModule", "kind": "module", "items": [ @@ -140,7 +140,7 @@ extracting docs for src/DocExtractionRes.res }] }, { - "id": "ModuleWithThingsThatShouldNotBeExported.DocExtractionRes", + "id": "DocExtractionRes.ModuleWithThingsThatShouldNotBeExported", "name": "ModuleWithThingsThatShouldNotBeExported", "kind": "module", "items": [ From 70f19fa34f990e645a051946409decf937072d2f Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Sun, 1 Oct 2023 23:48:58 -0300 Subject: [PATCH 09/10] emit valid id path --- analysis/src/DocExtraction.ml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/analysis/src/DocExtraction.ml b/analysis/src/DocExtraction.ml index 4bf20425e..4ea095755 100644 --- a/analysis/src/DocExtraction.ml +++ b/analysis/src/DocExtraction.ml @@ -304,7 +304,9 @@ let extractDocs ~path ~debug = | Module (Ident p) -> (* module Whatever = OtherModule *) let aliasToModule = p |> pathIdentToString in - let modulePath = aliasToModule :: modulePath in + let id = + (modulePath |> List.rev |> List.hd) ^ "." ^ item.name + in let items = match ProcessCmt.fileForModule ~package:full.package @@ -313,14 +315,14 @@ let extractDocs ~path ~debug = | None -> [] | Some file -> let docs = - extractDocsForModule ~modulePath file.structure + extractDocsForModule ~modulePath:[id] file.structure in docs.items in Some (ModuleAlias { - id = modulePath |> List.rev |> SharedTypes.ident; + id; name = item.name; items; docstring = item.docstring |> List.map String.trim; From 14fabbdb98ef7c715515cc958c0254702bfab986 Mon Sep 17 00:00:00 2001 From: Pedro Castro Date: Mon, 2 Oct 2023 00:05:25 -0300 Subject: [PATCH 10/10] update tests --- analysis/tests/src/expected/DocExtractionRes.res.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/analysis/tests/src/expected/DocExtractionRes.res.txt b/analysis/tests/src/expected/DocExtractionRes.res.txt index 4ae808089..b591bfd91 100644 --- a/analysis/tests/src/expected/DocExtractionRes.res.txt +++ b/analysis/tests/src/expected/DocExtractionRes.res.txt @@ -94,7 +94,7 @@ extracting docs for src/DocExtractionRes.res "kind": "module", "items": [ { - "id": "DocExtractionRes.AnotherModule.SomeInnerModule", + "id": "DocExtractionRes.LinkedModule", "kind": "moduleAlias", "name": "LinkedModule", "docstrings": ["This links another module. Neat."],