Skip to content

[DocGen]: Polish #796

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Oct 2, 2023
Merged

[DocGen]: Polish #796

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
b7683c8
emit items from module alias
aspeddro Jul 27, 2023
ec7c53a
Merge branch 'doc-extraction' into doc-extraction-expand-module-alias
aspeddro Sep 27, 2023
37a5df7
add error msg
aspeddro Sep 28, 2023
f7e94d3
rename fields
aspeddro Sep 28, 2023
6756e0d
remove double name field
aspeddro Sep 29, 2023
4b3479b
add ocaml.text attr
aspeddro Sep 29, 2023
01631e9
search for all attrs
aspeddro Sep 30, 2023
e5937e0
fix id module
aspeddro Sep 30, 2023
323758d
update tests
aspeddro Sep 30, 2023
70f19fa
emit valid id path
aspeddro Oct 2, 2023
14fabbd
update tests
aspeddro Oct 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
65 changes: 42 additions & 23 deletions analysis/src/DocExtraction.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,6 @@ type constructorDoc = {
deprecated: string option;
}

type docsForModuleAlias = {
id: string;
docstring: string list;
name: string;
signature: string;
}

type docItemDetail =
| Record of {fieldDocs: fieldDoc list}
| Variant of {constructorDocs: constructorDoc list}
Expand All @@ -41,7 +34,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;
Expand Down Expand Up @@ -72,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)
Expand All @@ -94,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
Expand Down Expand Up @@ -170,7 +168,12 @@ let rec stringifyDocItem ?(indentation = 0) ~originalEnv (item : docItem) =
("kind", Some (wrapInQuotes "moduleAlias"));
("name", Some (wrapInQuotes m.name));
("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) =
Expand Down Expand Up @@ -225,8 +228,6 @@ let typeDetail typ ~env ~full =
})
| _ -> None

exception Invalid_file_type

let makeId modulePath ~identifier =
identifier :: modulePath |> List.rev |> SharedTypes.ident

Expand All @@ -235,7 +236,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 =
Expand All @@ -251,7 +255,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
Expand All @@ -260,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;
Expand Down Expand Up @@ -297,15 +304,27 @@ 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
aliasToModule
with
| None -> []
| Some file ->
let docs =
extractDocsForModule ~modulePath:[id] file.structure
in
docs.items
in
Some
(ModuleAlias
{
id = modulePath |> List.rev |> SharedTypes.ident;
signature =
Printf.sprintf "module %s = %s" item.name
aliasToModule;
id;
name = item.name;
items;
docstring = item.docstring |> List.map String.trim;
})
| Module (Structure m) ->
Expand Down
2 changes: 1 addition & 1 deletion analysis/src/ProcessAttributes.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
[
{
Expand Down
8 changes: 5 additions & 3 deletions analysis/src/ProcessCmt.ml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion analysis/tests/src/expected/DocExtraction2.res.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
2 changes: 1 addition & 1 deletion analysis/tests/src/expected/DocExtraction2.resi.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": [
Expand Down
28 changes: 14 additions & 14 deletions analysis/tests/src/expected/DocExtractionRes.res.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
Expand All @@ -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": [
Expand All @@ -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"
}]
Expand All @@ -89,16 +89,16 @@ extracting docs for src/DocExtractionRes.res
}]
},
{
"id": "AnotherModule.DocExtractionRes",
"id": "DocExtractionRes.AnotherModule",
"name": "AnotherModule",
"kind": "module",
"items": [
{
"id": "DocExtractionRes.AnotherModule.SomeInnerModule",
"id": "DocExtractionRes.LinkedModule",
"kind": "moduleAlias",
"name": "LinkedModule",
"docstrings": ["This links another module. Neat."],
"signature": "module LinkedModule = SomeInnerModule"
"items": []
},
{
"id": "DocExtractionRes.AnotherModule.callback",
Expand All @@ -123,9 +123,9 @@ extracting docs for src/DocExtractionRes.res
"detail":
{
"kind": "variant",
"constructorDocs": [
"items": [
{
"constructorName": "SomeStuff",
"name": "SomeStuff",
"docstrings": ["This has inline records..."],
"signature": "SomeStuff"
}]
Expand All @@ -140,7 +140,7 @@ extracting docs for src/DocExtractionRes.res
}]
},
{
"id": "ModuleWithThingsThatShouldNotBeExported.DocExtractionRes",
"id": "DocExtractionRes.ModuleWithThingsThatShouldNotBeExported",
"name": "ModuleWithThingsThatShouldNotBeExported",
"kind": "module",
"items": [
Expand Down